Package ghidra.xml

Interface XmlPullParser

All Known Implementing Classes:
AbstractXmlPullParser, NonThreadedXmlPullParserImpl
public interface XmlPullParser
An interface describing the API for the XML pull parsing system. This is similar to XmlParser, except that it has slightly different methods and IS case sensitive, conforming to the XML spec.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    discardSubTree()
    Discards the current subtree.
    int
    discardSubTree(XmlElement element)
    Discards a subtree.
    int
    discardSubTree(String name)
    Discards the current subtree.
    void
    dispose()
    Disposes all resources of the parser.
    XmlElement
    end()
    Returns the next element, which must be an end element.
    XmlElement
    end(XmlElement element)
    Returns the next element, which must be an end element, and must match the supplied XmlElement's name (presumably the start element of the subtree).
    int
    getColumnNumber()
    Returns the current column number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
    int
    getCurrentLevel()
    The current element level, as if the XML document was a tree.
    int
    getLineNumber()
    Returns the current line number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
    String
    getName()
    Returns the name of this parser.
    String
    getProcessingInstruction(String name, String attribute)
    Returns the value of the attribute of the processing instruction.
    boolean
    hasNext()
    Returns whether there is a next element.
    boolean
    isPullingContent()
    Returns whether the parser will return content elements as well as start and end elements (they're always accumulated and provided in the appropriate end element).
    XmlElement
    next()
    Returns the next element, removing it from the queue (assuming there is such a next element).
    XmlElement
    peek()
    Returns the next element, without removing it from the queue (assuming there is such a next element).
    void
    setPullingContent(boolean pullingContent)
    Set whether the parser will return content elements.
    XmlElement
    softStart(String... names)
    Returns the next element, which must be a start element, and must be one of the supplied names (if provided).
    XmlElement
    start(String... names)
    Returns the next element, which must be a start element, and must be one of the supplied names (if provided).

  • Method Details

    • getName

      String getName()
      Returns the name of this parser.
      Returns:
      the name of this parser

    • getProcessingInstruction

      String getProcessingInstruction(String name, String attribute)
      Returns the value of the attribute of the processing instruction. For example, <?program_dtd version="1"?>
      Parameters:
      name - the name of the processing instruction
      attribute - the name of the attribute
      Returns:
      the value of the attribute of the processing instruction

    • getLineNumber

      int getLineNumber()
      Returns the current line number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
      Returns:
      the current line number

    • getColumnNumber

      int getColumnNumber()
      Returns the current column number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
      Returns:
      the current column number

    • isPullingContent

      boolean isPullingContent()
      Returns whether the parser will return content elements as well as start and end elements (they're always accumulated and provided in the appropriate end element).
      Returns:
      whether the parser will return content elements

    • setPullingContent

      void setPullingContent(boolean pullingContent)
      Set whether the parser will return content elements. Note that this method may throw an exception if the parser cannot comply with the setting (usually when setting to true).
      Parameters:
      pullingContent - whether the parser will return content elements

    • getCurrentLevel

      int getCurrentLevel()
      The current element level, as if the XML document was a tree. The root element is at level 0. Each child is at a level one higher than its parent. Note that this is the same as peek().getLevel().
      Returns:
      the current element level

    • hasNext

      boolean hasNext()
      Returns whether there is a next element.
      Returns:
      whether there is a next element

    • peek

      XmlElement peek()
      Returns the next element, without removing it from the queue (assuming there is such a next element). This is very useful for examining the next item to decide who should handle the subtree, and then delegating to a subordinate with the parser state intact.
      Returns:
      the next element, without removing it

    • next

      XmlElement next()
      Returns the next element, removing it from the queue (assuming there is such a next element). This method should be used RARELY. Typically, when you're reading XML, you almost always at least know that you're either starting or ending a subtree, so start() or end() should be used instead. The only time you really might need to use this is if you don't really know where you are and you need to pop elements off until you synchronize back into a sane state.
      Returns:
      the next element, removing it

    • start

      XmlElement start(String... names)
      Returns the next element, which must be a start element, and must be one of the supplied names (if provided). This method is very useful for starting a subtree, and throws an XmlException if the next element does not conform to your specification.
      Parameters:
      names - optional vararg Strings which start element name must be one of
      Returns:
      the next element (which is a start element)

    • end

      XmlElement end()
      Returns the next element, which must be an end element. The name doesn't matter. This method throws an XmlException if the next element is not an end element. Use this method when you really know you're matching the right end and want to avoid extra constraint checks.
      Returns:
      the next element (which is an end element)

    • end

      XmlElement end(XmlElement element)
      Returns the next element, which must be an end element, and must match the supplied XmlElement's name (presumably the start element of the subtree). This method throws an XmlException if the next element is not an end element, or if the name doesn't match.
      Parameters:
      element - the presumed start element to match names
      Returns:
      the next element (which is an end element)

    • softStart

      XmlElement softStart(String... names)
      Returns the next element, which must be a start element, and must be one of the supplied names (if provided). This method is very useful for starting a subtree, but differs from start(...) in that failures are soft. This means that if the next element isn't a start element, or doesn't match one of the optional provided names, null is returned (instead of raising an XmlException).
      Parameters:
      names - optional vararg Strings which start element name must be one of
      Returns:
      the next element (which is a start element) or null

    • discardSubTree

      int discardSubTree()
      Discards the current subtree. If the current element (peek()) is a content or end element, then just that element is discarded. If it's a start element, then the entire subtree starting with the start element is discarded (i.e. next() is called until the current element is now the element after the subtree's end element).
      Returns:
      the number of elements discarded

    • discardSubTree

      int discardSubTree(String name)
      Discards the current subtree. The current element must be a start element, and must be named name, otherwise an XmlException is thrown.
      Parameters:
      name - what the current start element must be named
      Returns:
      the number of elements discarded

    • discardSubTree

      int discardSubTree(XmlElement element)
      Discards a subtree. The element provided is used as the "start" of the subtree (although it doesn't actually have to be a start element; only its name and level are used). The queue of elements is discarded such that the last element discarded is an end element, has the same name as the provided element, and is the same level as the provided element. If the provided element's level is higher than the current level, then nothing is discarded.
      Parameters:
      element - the element provided as the "start" element
      Returns:
      the number of elements discarded

    • dispose

      void dispose()
      Disposes all resources of the parser. It's important that this is called when a client is finished with the parser, because this allows files to be closed, threads to be stopped, etc.