XMLDocument2 - Délimité, global

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 8 minutes de lecture

    • L’API XMLDocument2 est une couche d’objet JavaScript permettant d’analyser et d’extraire des données XML à partir d’une chaîne XML.

    Utilisez cette classe JavaScript pour créer un objet à partir d’une chaîne XML, généralement une valeur de retour d’un appel de service Web, ou de la charge utile XML de la file d’attente ECC. L’utilisation de l’objet XMLDocument2 dans une règle métier JavaScript vous permet d’interroger directement des valeurs à partir des éléments et attributs XML.

    Une chaîne XML a une structure arborescente et les parties de la structure sont appelées nœuds. Un objet XMLDocument2 traite deux types de nœuds, l’élément et l’élément document. Un nœud d’élément est un nœud portant un nom et éventuellement des attributs et des nœuds enfants. Un noeud document-element est le noeud racine de l’arborescence XML. C’est le seul nœud sans nœud parent.

    Remarque :
    Cette API fonctionne pour les applications incluses dans le périmètre ou globales.

    XMLDocument2 inclus dans le périmètre : XMLDocument2()

    Crée un objet XMLDocument2.

    Tableau 1. Paramètres
    Nom Type Description
    Aucun

    XMLDocument2 inclus dans le périmètre : XMLDocument2( GlideScriptableInputStream, inputStream)

    Crée un objet XMLDocument2 à partir d’un flux de pièces jointes.

    Tableau 2. Paramètres
    Nom Type Description
    inputStream (en anglais seulement) GlideScriptableInputStream Flux d’entrée encapsulé par l’objet XMLDocument2.

    XMLDocument2 inclus dans le périmètre : createElement(nom de chaîne)

    Crée et ajoute un nœud d’élément au nœud actuel. Le nom de l’élément est la chaîne transmise en tant que paramètre. Le nouvel élément n’a pas de nœuds enfants de texte.

    Tableau 3. Paramètres
    Nom Type Description
    nom Chaîne Nom du nouvel élément.
    Tableau 4. Renvoie
    Type Description
    Nœud XML Nœud XML actuel. 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString); 
xmlDoc.createElement("new2"); 
 
gs.info(xmlDoc);
    Sortie :
    ?xml version="1.0" encoding="UTF-8"?>
<test>  
    <one>    
        <two att="xxx">abcd1234</two>    
            <three att="yyy" boo="yah">1234abcd</three>    
        <two>another</two>  
    </one>  
    <number>1234</number>
    <new2></new2>
</test>

    XMLDocument2 inclus dans le périmètre : createElementWithTextValue(nom de chaîne, valeur de chaîne)

    Crée et ajoute un nœud d’élément avec un nœud enfant de texte au nœud actuel.

    Tableau 5. Paramètres
    Nom Type Description
    nom Chaîne Nom de l’élément à ajouter.
    valide Chaîne Valeur de texte de l’élément.
    Tableau 6. Renvoie
    Type Description
    Nœud XML Nœud XML actuel. 
    var xmlString = "<test>" +
    "  <one>" +
    "    <two att=\"xxx\">abcd1234</two>" +
    "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
    "    <two>another</two>" +
    "  </one>" +
    "  <number>1234</number>" +
    "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString); 
xmlDoc.createElementWithTextValue("new", "test");
gs.info(xmlDoc);
    Sortie :
    <?xml version="1.0" encoding="UTF-8"?>
    <test>
        <one>
            <two att="xxx">abcd1234</two>    
            <three att="yyy" boo="yah">1234abcd</three>    
            <two>another</two>  
        </one>  
        <number>1234</number>
        <new>test</new>
    </test>

    XMLDocument2 inclus dans le périmètre : getDocumentElement()

    Obtient le nœud d’élément de document de l’objet XMLdocument2. Le nœud d’élément de document est le nœud racine.

    Tableau 7. Paramètres
    Nom Type Description
    Aucun
    Tableau 8. Renvoie
    Type Description
    Nœud XML L’élément de document. 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);
//returns the root node of the document tree.
var rootNode = xmlDoc.getDocumentElement();
gs.info(rootNode.getTextContent());
    Sortie :
    abcd1234    1234abcd    another    1234

    XMLDocument2 inclus dans le périmètre : getFirstNode(String xPath)

    Obtient le premier nœud dans le xPath spécifié.

    Cette méthode ne prend en charge qu’un sous-ensemble d’expressions xPath de prédicat. Par exemple, supposons le document suivant :
    <store> 
    <resources company="ABC Inc"> 
        <resources type="servers" /> 
    </resources> 
    <resources company="XYZ Inc"> 
        <resource type="bookstore"> 
            <book> 
                <title>Windows</title> 
                <price>10</price> 
            </book> 
            <book year="2009"> 
                <title>Harry Potter</title> 
                <price>50</price> 
            </book> 
            <book year="1999"> 
                <title>Learning XML</title> 
                <price>120</price> 
            </book> 
            <book year="2019"> 
                <title>Learning Java</title> 
                <price>99</price> 
            </book> 
        </resource> 
    </resources> 
</store>
    Cette méthode prend en charge les expressions xPath suivantes avec des prédicats :
    "/store/resources/resource[@type='bookstore']/book[@year='1999']", 
"/store/resources/resource[@type='bookstore']/book[@year]", 
"/store/resources/resource[@type='bookstore']/book[price > 100]"
    Toutefois, il ne prend pas en charge les expressions xPath suivantes avec prédicats :
    "/store/resources/resource[@type='bookstore']/book[2]", 
"/store/resources/resource[@type='bookstore']/book[last()]", 
"/store/resources/resource[@type='bookstore']/book[position()>2]"

    Pour contourner ce problème, utilisez xPath sans prédicats, tels que « /store/resources/resource[@type='bookstore']/book »), puis filtrez les nœuds du script à l’aide des méthodes getFirstNode() et getNextNode().

    Tableau 9. Paramètres
    Nom Type Description
    xPath Chaîne xPath à partir duquel obtenir le nœud.
    Tableau 10. Renvoie
    Type Description
    Nœud XML Le premier nœud. 
    var xmlString = "<test>" +
  "  <one>" +
  "    <two att=\"xxx\">abcd1234</two>" +
  "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
  "    <two>another</two>" +
  "  </one>" +
  "  <number>1234</number>" +
  "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);
var foo = xmlDoc.getFirstNode('/test/one/two');
gs.info(foo.getTextContent());
    Sortie :
    abcd1234

    XMLDocument2 inclus dans le périmètre : getNextNode(Object current)

    Obtient le nœud après le nœud spécifié.

    Tableau 11. Paramètres
    Nom Type Description
    current Objet Le nœud actuel.
    Tableau 12. Renvoie
    Type Description
    Nœud XML Le nœud suivant. 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);
var foo = xmlDoc. getFirstNode('/test/one/two');
var foo2 = xmlDoc.getNextNode(foo);
gs.info(foo.getTextContent());
gs.info(foo2.getTextContent());
    Sortie :
    abcd1234

another

    XMLDocument2 inclus dans le périmètre : getNode(String xPath)

    Obtient le nœud spécifié dans xPath.

    Remarque :
    Cette méthode est destinée à être utilisée avec des documents de petite taille, car elle analyse l’ensemble du document pour qu’il corresponde à l’expression xPath. Si le document est trop volumineux, une erreur de mémoire insuffisante peut se produire. Pour les documents volumineux, utilisez les méthodes getFirstNode(String xPath) et getNextNode(Object current), qui sont conçues pour parcourir le document en continu sans analyser l’ensemble du document.
    Tableau 13. Paramètres
    Nom Type Description
    xPath Chaîne xChemin du nœud à obtenir.
    Tableau 14. Renvoie
    Type Description
    Nœud XML Nœud XML actuel. 
    /*
 * Checks if given node indeed of given tag.
 * Params:
 *  tag - String, name of tag to check
 *  node - XMLNode, node in which to check for the tag
 * Returns:
 *  true, if tag is present
 *  false, otherwise
 */
function isNodeOfTag (node, tag) {
  try {
    if (tag == node.getNodeName()) {
      gs.info("Given node belongs to tag " + tag);
      return true;
    }
  } catch (error) {
    gs.error("Given node might not belong to tag " + tag + ". Error while checking: " + error);
    return false;
  }
}

var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";

var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);

var node = xmlDoc.getNode("/test/one/two"); // tag 'two' is present in this XML.
isNodeOfTag(node, "two");

var node = xmlDoc.getNode("/test/one/four"); // tag 'four' is not present in this XML.
isNodeOfTag(node, "four");
    Sortie :
    Given node belongs to tag two
Given node might not belong to tag four. Error while checking: java.lang.NullPointerException

    XMLDocument2 inclus dans le périmètre : getNodeText(String xPath)

    Obtient tous les nœuds enfants de texte à partir du nœud référencé dans le XPath spécifié.

    Tableau 15. Paramètres
    Nom Type Description
    xPath Chaîne XPath du texte à obtenir.
    Tableau 16. Renvoie
    Type Description
    Chaîne Textez les enfants dans le XPath. 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString); 
gs.info(xmlDoc.getNodeText("//two"));

    Sortie :

    abcd1234

    XMLDocument2 inclus dans le périmètre : parseXML(String xmlDoc)

    Analyse la chaîne XML et la charge dans l’objet XMLDocument2.

    Tableau 17. Paramètres
    Nom Type Description
    xmlDoc (en anglais seulement) Chaîne Le document à analyser.
    Tableau 18. Renvoie
    Type Description
    Booléen Marqueur indiquant si le contenu a été analysé.

    Cet exemple analyse la xmlString et la charge dans l’objet xmlDocument2.

    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString); 
var rootNode = xmlDoc.getDocumentElement();

    XMLDocument2 inclus dans le périmètre : setCurrentElement(élément XMLNode)

    Fait du nœud transmis en tant que paramètre le nœud actuel.

    Tableau 19. Paramètres
    Nom Type Description
    élément Nœud XML Le nœud d’élément à définir en tant que nœud actuel.
    Tableau 20. Renvoie
    Type Description
    nul 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);
//returns the root node of the document tree.
var rootNode = xmlDoc.getDocumentElement(); //returns org.w3c.dom.Element
// sets the root node as the current element
xmlDoc.setCurrentElement(rootNode);

    XMLDocument2 inclus dans le champ d’application : setEnableCDATAReporting(Boolean enable)

    Définit si les nœuds sont traités comme CDATA ou comme du texte normal après l’analyse. Le reporting CDATA est désactivé par défaut.

    Cette méthode doit être appelée avec XMLDocument2 inclus dans le périmètre : parseXML(String xmlDoc).

    Voir aussi : XMLNode inclus dans le périmètre : isCDATANode().

    Tableau 21. Paramètres
    Nom Type Description
    activer Booléen Marqueur indiquant s’il faut traiter les nœuds CDATA en tant que nœuds CDATA ou nœuds de texte standard.
    Valeurs valides :
    • vrai : activez la génération de rapports CDATA.
    • false : Traitez les nœuds CDATA comme des nœuds de texte normaux après l’analyse et concaténez-les avec le texte adjacent.

    Valeur par défaut : false
    Tableau 22. Renvoie
    Type Description
    Aucun

    L’exemple suivant montre comment CDATA est analysé dans un élément avec la génération de rapports CDATA activée. Le résultat de content.getFirstChild() est un élément qui contient une autre valeur de texte. Cet élément contient en interne les informations qui l’identifient en tant que type CDATA. Le résultat de content.getLastChild() est un élément qui contient l’élément de valeur textuelle. Cet élément contient les informations en interne sous forme de type texte.

    var xmlString = "<test>" +
  "  <one>" +
  "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
  "    <two><![CDATA[another]]>element</two>" +
  "  </one>" +
  "  <number>1234</number>" 
  "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.setEnableCDATAReporting(true); // Enable CDATA reporting
xmlDoc.parseXML(xmlString);
var content = xmlDoc.getFirstNode('/test/one/two');
gs.info(content.getFirstChild().getTextContent()); // prints "another"
gs.info(content.getLastChild().getTextContent()); // prints "element"

    Sortie :

    another
element
    Remarque :
    Si la génération de rapports CDATA n’est pas activée dans l’exemple, l’enfant entier concatène le CDATA sous forme de texte avec le reste du texte (élément) de chaque ligne, comme suit :
    anotherelement
anotherelement

    XMLDocument2 inclus dans le périmètre : setNamespaceAware(compatible avec les booléens)

    Lorsqu’il est défini sur vrai, l’objet XMLDocument2 traite le document avec des espaces de noms XML.

    Si vous ne définissez pas cette option, un document XML avec des espaces de noms ne sera pas énuméré correctement et une recherche XPath échouera. 

    Tableau 23. Paramètres
    Nom Type Description
    conscient Booléen Si vrai, l’objet XMLDocument2 traite le document avec des espaces de noms XML.
    Tableau 24. Renvoie
    Type Description
    nul

    XMLDocument2 inclus dans le périmètre : toString()

    Renvoie une chaîne contenant le code XML.

    Tableau 25. Paramètres
    Nom Type Description
    Aucun
    Tableau 26. Renvoie
    Type Description
    Chaîne Chaîne contenant le code XML. 
    var xmlString = "<test>" +
                "  <one>" +
                "    <two att=\"xxx\">abcd1234</two>" +
                "    <three boo=\"yah\" att=\"yyy\">1234abcd</three>" +
                "    <two>another</two>" +
                "  </one>" +
                "  <number>1234</number>" +
                "</test>";
var xmlDoc = new XMLDocument2();
xmlDoc.parseXML(xmlString);
gs.info(xmlDoc.toString());
    Sortie : des sauts de ligne ont été ajoutés à la sortie pour plus de lisibilité.
    <?xml version="1.0" encoding="UTF-8"?>
<test>  
<one>    
<two att="xxx">abcd1234</two>    
<three att="yyy" boo="yah">1234abcd</three>    
<two>another</two>  
</one>  
<number>1234</number>
</test>