Package groovy.xml.dom

Class DOMCategory

java.lang.Object
groovy.xml.dom.DOMCategory
public class DOMCategory extends Object
Category class which adds GPath style operations to Java's DOM classes. These helpers provide property access, traversal, mutation, and XPath support for W3C DOM nodes in a style similar to Groovy's XML slurper APIs.

  • Constructor Details

    • DOMCategory

      public DOMCategory()

  • Method Details

    • isGlobalTrimWhitespace

      public static boolean isGlobalTrimWhitespace()
      Returns:
      true if text elements are trimmed before returning; default false

    • setGlobalTrimWhitespace

      public static void setGlobalTrimWhitespace(boolean trimWhitespace)
      Whether text content is trimmed (removing leading and trailing whitespace); default false. WARNING: this is a global setting. Altering it will affect all DOMCategory usage within the current Java process. It is not recommended that this is altered; instead call the trim() method on the returned text, but the flag is available to support legacy Groovy behavior.
      Parameters:
      trimWhitespace - the new value

    • isGlobalKeepIgnorableWhitespace

      public static boolean isGlobalKeepIgnorableWhitespace()
      Returns:
      true if ignorable whitespace (e.g. whitespace between elements) is kept; default false

    • setGlobalKeepIgnorableWhitespace

      public static void setGlobalKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)
      Whether ignorable whitespace (e.g. whitespace between elements) is kept (default false). WARNING: this is a global setting. Altering it will affect all DOMCategory usage within the current Java process.
      Parameters:
      keepIgnorableWhitespace - the new value

    • get

      public static Object get(Element element, String elementName)
      Resolves a GPath-style property lookup against a DOM element. Supports child element lookup, attribute access using @name, parent lookup using .., and depth-first traversal using **.
      Parameters:
      element - the element to query
      elementName - the property or selector name
      Returns:
      the matching child nodes, attribute value, parent node, or traversal view

    • get

      public static Object get(NodeList nodeList, String elementName)
      Resolves a GPath-style property lookup against every element in a node list.
      Parameters:
      nodeList - the nodes to query
      elementName - the property or selector name
      Returns:
      an aggregated result for the supplied selector

    • get

      public static Object get(NamedNodeMap nodeMap, String elementName)
      Returns the value of a named attribute from a DOM attribute map.
      Parameters:
      nodeMap - the attributes to query
      elementName - the attribute name
      Returns:
      the attribute value

    • attributes

      public static NamedNodeMap attributes(Element element)
      Returns the attributes belonging to the supplied element.
      Parameters:
      element - the element whose attributes should be returned
      Returns:
      the element's attribute map

    • size

      public static int size(NamedNodeMap namedNodeMap)
      Returns the number of attributes in a DOM attribute map.
      Parameters:
      namedNodeMap - the attributes to inspect
      Returns:
      the number of attributes

    • getAt

      public static Node getAt(Node o, int i)
      Returns the indexed child visible through DOMCategory navigation. Negative indices count backward from the end of the result.
      Parameters:
      o - the node or element to index
      i - the zero-based index
      Returns:
      the selected node, or null if the index is out of range

    • getAt

      public static Node getAt(groovy.xml.dom.DOMCategory.NodeListsHolder o, int i)
      Returns the indexed node from an aggregated node-list view. Negative indices count backward from the end of the result.
      Parameters:
      o - the aggregated node-list view
      i - the zero-based index
      Returns:
      the selected node, or null if the index is out of range

    • getAt

      public static Node getAt(groovy.xml.dom.DOMCategory.NodesHolder o, int i)
      Returns the indexed node from a simple node-list view. Negative indices count backward from the end of the result.
      Parameters:
      o - the node-list view
      i - the zero-based index
      Returns:
      the selected node, or null if the index is out of range

    • getAt

      public static NodeList getAt(Node o, IntRange r)
      Returns a range of child nodes visible through DOMCategory navigation. Negative bounds count backward from the end of the result.
      Parameters:
      o - the node or element to slice
      r - the range of indices to select
      Returns:
      a node-list view containing the selected nodes

    • getAt

      public static NodeList getAt(groovy.xml.dom.DOMCategory.NodeListsHolder o, IntRange r)
      Returns a range of nodes from an aggregated node-list view.
      Parameters:
      o - the aggregated node-list view
      r - the range of indices to select
      Returns:
      a node-list view containing the selected nodes

    • getAt

      public static NodeList getAt(groovy.xml.dom.DOMCategory.NodesHolder o, IntRange r)
      Returns a range of nodes from a simple node-list view.
      Parameters:
      o - the node-list view
      r - the range of indices to select
      Returns:
      a node-list view containing the selected nodes

    • name

      public static String name(Node node)
      Returns the DOM node name used for GPath name lookups.
      Parameters:
      node - the node to inspect
      Returns:
      the node name

    • parent

      public static Node parent(Node node)
      Returns the parent DOM node.
      Parameters:
      node - the node whose parent should be returned
      Returns:
      the parent node, or null for a root node

    • text

      public static String text(Node node)
      Returns the text visible from a DOM node. Text and CDATA nodes return their value directly; other nodes concatenate descendant text.
      Parameters:
      node - the node to inspect
      Returns:
      the concatenated text for the node

    • text

      public static String text(NodeList nodeList)
      Concatenates the text visible from every node in the list.
      Parameters:
      nodeList - the nodes to inspect
      Returns:
      the concatenated text for all nodes in document order

    • list

      public static List<Node> list(NodeList self)
      Copies a NodeList into a mutable List.
      Parameters:
      self - the node list to copy
      Returns:
      a list containing the nodes from the node list

    • depthFirst

      public static NodeList depthFirst(Element self)
      Returns a depth-first traversal view containing the element itself followed by descendant elements.
      Parameters:
      self - the root element for traversal
      Returns:
      a node-list view in depth-first order

    • setValue

      public static void setValue(Element self, String value)
      Sets the value of the first child text node, creating one if the element has no children.
      Parameters:
      self - the element to update
      value - the text value to set

    • putAt

      public static void putAt(Element self, String property, Object value)
      Performs a GPath-style property assignment on an element. Attribute assignments use the @name form; all other properties are delegated to Groovy property handling.
      Parameters:
      self - the element to update
      property - the property or attribute selector
      value - the value to assign

    • appendNode

      public static Element appendNode(Element self, Object name)
      Appends a child element with the given name.
      Parameters:
      self - the parent element
      name - the child element name, optionally a QName
      Returns:
      the appended child element

    • appendNode

      public static Element appendNode(Element self, Object name, Map attributes)
      Appends a child element with the given name and attributes.
      Parameters:
      self - the parent element
      name - the child element name, optionally a QName
      attributes - the attributes to apply to the new child
      Returns:
      the appended child element

    • appendNode

      public static Element appendNode(Element self, Object name, String value)
      Appends a child element with the given name and optional text value.
      Parameters:
      self - the parent element
      name - the child element name, optionally a QName
      value - the text value to append inside the new child, or null
      Returns:
      the appended child element

    • appendNode

      public static Element appendNode(Element self, Object name, Map attributes, String value)
      Appends a child element with attributes and optional text content.
      Parameters:
      self - the parent element
      name - the child element name, optionally a QName
      attributes - the attributes to apply to the new child
      value - the text value to append inside the new child, or null
      Returns:
      the appended child element

    • replaceNode

      public static Node replaceNode(groovy.xml.dom.DOMCategory.NodesHolder self, Closure c)
      Replaces a single selected node with the nodes produced by the supplied builder closure.
      Parameters:
      self - the node selection to replace; it must contain exactly one node
      c - the builder closure creating replacement nodes
      Returns:
      the removed node
      Throws:
      GroovyRuntimeException - if the selection does not contain exactly one node

    • replaceNode

      public static Node replaceNode(Node self, Closure c)
      Replaces a node with the nodes produced by the supplied builder closure.
      Parameters:
      self - the node to replace
      c - the builder closure creating replacement nodes
      Returns:
      the removed node
      Throws:
      UnsupportedOperationException - if self is the document root

    • plus

      public static void plus(Element self, Closure c)
      Adds sibling nodes after the supplied element using the builder closure.
      Parameters:
      self - the element after which new siblings should be inserted
      c - the builder closure creating the sibling nodes
      Throws:
      UnsupportedOperationException - if self is the document root

    • localText

      public static List<String> localText(Element self)
      Returns the list of any direct String nodes of this node.
      Returns:
      the list of String values from this node
      Since:
      2.3.0

    • plus

      public static void plus(NodeList self, Closure c)
      Adds sibling nodes after every element in the supplied node list.
      Parameters:
      self - the elements after which new siblings should be inserted
      c - the builder closure creating the sibling nodes

    • breadthFirst

      public static NodeList breadthFirst(Element self)
      Returns a breadth-first traversal view containing the element and its descendants level by level.
      Parameters:
      self - the root element for traversal
      Returns:
      a node-list view in breadth-first order

    • children

      public static NodeList children(Element self)
      Returns the child nodes visible to DOMCategory navigation. Child elements are always included, and retained text nodes are included when they are not discarded as ignorable whitespace.
      Parameters:
      self - the parent element
      Returns:
      a node-list view of the visible children

    • toString

      public static String toString(Object o)
      Renders a DOMCategory value in a GPath-friendly string form.
      Parameters:
      o - the value to render
      Returns:
      text for text nodes, list-style output for node lists, or o.toString()

    • xpath

      public static Object xpath(Node self, String expression, QName returnType)
      Evaluates an XPath expression against the supplied node.
      Parameters:
      self - the context node
      expression - the XPath expression to evaluate
      returnType - the desired XPath return type
      Returns:
      the XPath evaluation result
      Throws:
      GroovyRuntimeException - if the expression cannot be evaluated

    • xpath

      public static String xpath(Node self, String expression)
      Evaluates an XPath expression against the supplied node and returns the string result.
      Parameters:
      self - the context node
      expression - the XPath expression to evaluate
      Returns:
      the string result of the XPath evaluation
      Throws:
      GroovyRuntimeException - if the expression cannot be evaluated

    • size

      public static int size(NodeList self)
      Returns the number of nodes in the supplied node list.
      Parameters:
      self - the node list to inspect
      Returns:
      the number of nodes

    • isEmpty

      public static boolean isEmpty(NodeList self)
      Determines whether the supplied node list is empty.
      Parameters:
      self - the node list to inspect
      Returns:
      true if the node list contains no nodes