XMLDocument2 : dans le champ d’application, global

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 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’une invocation de service Web, ou 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 les valeurs des éléments XML et des attributs.

    Une chaîne XML a une arborescence 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 avec un nom et éventuellement des attributs et des nœuds enfants. Un nœud document-élément est le nœud racine de l’arborescence XML. Il s’agit du 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 champ d’application : XMLDocument2()

    Crée un objet XMLDocument2.

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

    XMLDocument2 inclus dans le champ d’application : XMLDocument2 (GlideScriptableInputStream, inputStream)

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

    Tableau 2. Paramètres
    Nom Type Description
    Flux d’entrée GlideScriptableInputStream Flux d’entrée encapsulé par l’objet XMLDocument2.

    XMLDocument2 dans le champ d’application : createElement(nom de la 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 Le nom du nouvel élément.
    Tableau 4. Renvoie
    Type Description
    Code 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 dans le champ d’application : 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
    Code 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 dans le champ d’application : 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
    Code 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 dans le champ d’application : 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 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 dans le 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
    Code 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 dans le champ d’application : getNextNode(Objet actuel)

    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
    Code 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 dans le champ d’application : getNode(String xPath)

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

    Remarque :
    Cette méthode est destinée à être utilisée avec de petits documents car elle analyse l’intégralité du document pour correspondre à 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 sans l’analyser entièrement.
    Tableau 13. Paramètres
    Nom Type Description
    xPath Chaîne xPath du nœud à obtenir.
    Tableau 14. Renvoie
    Type Description
    Code 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 dans le champ d’application : getNodeText(String xPath)

    Obtient tous les nœuds enfants de texte 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 Envoyez un texte aux 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 dans le champ d’application : parseXML(String xmlDoc)

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

    Tableau 17. Paramètres
    Nom Type Description
    xmlDoc Chaîne Document à analyser.
    Tableau 18. 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 champ d’application : 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 Code 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 dans le champ d’application : setEnableCDATAReporting(Boolean enable)

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

    Cette méthode doit être appelée avec XMLDocument2 dans le champ d’application : parseXML(String xmlDoc).

    Voir aussi : XMLNode dans le champ d’application : isCDATANode().

    Tableau 21. Paramètres
    Nom Type Description
    activer Booléen Marqueur indiquant s’il faut gérer les nœuds CDATA comme des nœuds CDATA ou de texte normal.
    Valeurs valides :
    • true : activer la génération de rapports CDATA.
    • false : traitez les nœuds CDATA comme des nœuds de texte normal après les avoir analysés et concaténés avec le texte adjacent.

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

    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 l’identifiant comme un type CDATA. Le résultat de content.getLastChild() est un élément qui contient l’élément valeur text. Cet élément contient les informations en interne sous forme de type de 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 :
    Sans le reporting CDATA activé dans l’exemple, l’enfant entier concatène le CDATA sous forme de texte avec le reste du texte (élément) dans chaque ligne comme suit :
    anotherelement
anotherelement

    XMLDocument2 dans le champ d’application : setNamespaceAware(prenant en compte 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 cela, un document XML avec des espaces de noms ne sera pas énuméré correctement et une recherche XPath échouerait. 

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

    XMLDocument2 dans le champ d’application : toString()

    Renvoie une chaîne contenant le code XML.

    Tableau 25. Paramètres
    Nom Type Description
    Aucun
    Tableau 26. Renvoie
    Type Description
    Chaîne Une 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>