XMLDocument2 - Champ d’application, global

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 8 minutes de lecture

    • L’API XMLDocument2 fournit une couche d’objet JavaScript pour l’analyse et l’extraction des données XML 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 provenant 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 de demander 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 de deux types de nœuds, l’élément et l’élément document. Un nœud d’élément est un nœud avec un nom et éventuellement des attributs et des nœuds enfants. Un nœud document-element est le nœud racine de l’arborescence XML. C’est le seul nœud sans nœud parent.

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

    XMLDocument2 inclus dans le champ d’application : 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 paramètre. Le nouvel élément n’a pas de nœuds enfants de texte.

    Tableau 1. Paramètres
    Nom Type Description
    nom Chaîne Nom du nouvel élément.
    Tableau 2. Renvoie
    Type Description
    Xmlnode 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 3. 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 4. Renvoie
    Type Description
    Xmlnode 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 de l’élément document est le nœud racine.

    Tableau 5. Paramètres
    Nom Type Description
    Aucun
    Tableau 6. Renvoie
    Type Description
    Xmlnode 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. Prenons par exemple 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]"
    Cependant, il ne prend pas en charge les expressions xPath suivantes avec des 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 dans le script à l’aide des méthodes getFirstNode() et getNextNode().

    Tableau 7. Paramètres
    Nom Type Description
    Xpath Chaîne xPath à partir duquel obtenir le nœud.
    Tableau 8. Renvoie
    Type Description
    Xmlnode 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 9. Paramètres
    Nom Type Description
    current Objet Le nœud actuel.
    Tableau 10. Renvoie
    Type Description
    Xmlnode 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 le 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’intégralité du document.
    Tableau 11. Paramètres
    Nom Type Description
    Xpath Chaîne xChemin du noeud à obtenir.
    Tableau 12. Renvoie
    Type Description
    Xmlnode 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 13. Paramètres
    Nom Type Description
    Xpath Chaîne XPath du texte à obtenir.
    Tableau 14. Renvoie
    Type Description
    Chaîne Textez les enfants dans 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 15. Paramètres
    Nom Type Description
    xmlDoc Chaîne Le document à analyser.
    Tableau 16. Renvoie
    Type Description
    Booléen Marqueur indiquant si le contenu a été analysé.

    Cet exemple analyse la chaîne 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 17. Paramètres
    Nom Type Description
    élément Xmlnode Le nœud d’élément à définir en tant que nœud actuel.
    Tableau 18. 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 périmètre : setEnableCDATAReporting(Boolean enable)

    Définit si les nœuds sont traités comme CDATA ou comme du texte normal après l’analyse. La génération de rapports CDATA est désactivée par défaut.

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

    Voir aussi : Nœud XML inclus dans le périmètre - isCDATANode().

    Tableau 19. 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 de type texte normal.
    Valeurs valides :
    • true : 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 20. Renvoie
    Type Description
    Néant

    L’exemple suivant montre comment CDATA est analysé dans un élément où la génération de rapports CDATA est activée. Le résultat de content.getFirstChild() est un élément qui contient la valeur du texte un autre. 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 text value. Cet élément contient en interne les informations 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(prenant en charge les booléens)

    Lorsqu’il est défini sur true, 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 21. Paramètres
    Nom Type Description
    Conscient Booléen Si vrai, l’objet XMLDocument2 traite le document avec des espaces de noms XML.
    Tableau 22. Renvoie
    Type Description
    nul

    XMLDocument2 inclus dans le champ d’application - toString()

    Renvoie une chaîne contenant le code XML.

    Tableau 23. Paramètres
    Nom Type Description
    Aucun
    Tableau 24. 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>

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

    Crée un objet XMLDocument2.

    Tableau 25. Paramètres
    Nom Type Description
    Néant

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

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

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