Package com.chilkatsoft.chilkat2

Class Xml

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Xml
All Implemented Interfaces:
AutoCloseable
public class Xml extends ChilkatObject
<section class="xml-summary">

Load, navigate, search, edit, transform, and save in-memory XML trees.

Chilkat.Xml is the primary Chilkat class for in-memory XML tree manipulation. It supports loading and saving XML, navigating between elements, reading and writing text content, managing attributes, working with namespaces, adding and removing subtrees, searching by tag, content, or attribute, sorting child records, scrubbing XML, handling CDATA and XML declarations, storing binary data as Base64, and optionally compressing or encrypting element content.

Load and save XML

Load XML from strings, files, byte data, or other Chilkat objects, then save or emit formatted XML when processing is complete.

Navigate XML trees

Move through parent, child, sibling, and selected elements while working directly with the XML document structure.

Edit elements and attributes

Add, update, remove, or rename elements; set text content; and read, add, modify, or delete attributes.

Search and select

Locate elements by tag name, content, path, attribute value, or custom search patterns.

Namespaces and structure

Work with namespace-aware XML, declarations, CDATA, child ordering, sorting, and subtree insertion or removal.

Binary and protected content

Store binary data as Base64 and optionally compress or encrypt element content when XML carries encoded payloads.

Important usage distinction: Some methods return a new Xml object reference for the selected element, while methods ending in 2 update the caller's internal reference to point to a different element. This distinction is central when navigating and editing XML trees because it determines whether the current object stays where it is or moves to another element.

Common pattern: Load or create the XML document, navigate to the element of interest, read or modify content and attributes, add or remove child elements as needed, then save the updated XML. Use Chilkat.Xml for tree-oriented XML manipulation, and use Chilkat.XmlDSig, Chilkat.XmlDSigGen, or related classes when the task is XML digital signing or signature verification.

For an extended overview, see Xml Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Summary

    Constructors
    Constructor
    Description
    Xml()
    Creates a new Xml object.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    accumulateTagContent​(String tag, String skipTags)
    Traverses the subtree rooted at the calling element and concatenates the text content of all elements whose tag equals tag.
    void
    addAttribute​(String name, String value)
    Adds an attribute named name with the specified string value to the calling element.
    void
    addAttributeInt​(String name, int value)
    Adds an attribute named name whose value is the decimal representation of value.
    void
    addChildTree​(Xml tree)
    Adds the entire XML subtree referenced by tree as a new direct child of the calling element.
    void
    addOrUpdateAttribute​(String name, String value)
    Sets the string value of an attribute on the calling element.
    void
    addOrUpdateAttributeI​(String name, int value)
    Sets an integer-valued attribute on the calling element.
    void
    addStyleSheet​(String styleSheet)
    Adds an XML stylesheet processing instruction to the document.
    void
    addToAttribute​(String name, int amount)
    Treats the named attribute value as an integer, adds amount, and stores the resulting integer back in the attribute.
    void
    addToChildContent​(String tag, int amount)
    Finds the child identified by tag, interprets its content as an integer, adds amount, and stores the resulting integer as the child's new content.
    void
    addToContent​(int amount)
    Interprets this element's content as an integer, adds amount, and stores the resulting integer as the new content.
    void
    appendToContent​(String str)
    Appends str to the existing text content of the calling element without replacing its child elements.
    boolean
    childContentMatches​(String tagPath, String pattern, boolean caseSensitive)
    Returns true if the child identified by tagPath has content matching pattern; otherwise returns false.
    String
    chilkatPath​(String pathCmd)
    Evaluates a Chilkat-specific path command that can navigate from the current element, return element content or an attribute value, or move the caller's internal element reference.
    void
    clear()
    Clears the calling element by removing all child elements, attributes, and text content, and resets its tag name to unnamed.
    boolean
    contentMatches​(String pattern, boolean caseSensitive)
    Returns true if this element's content matches pattern; otherwise returns false.
    void
    copy​(Xml node)
    Copies the Tag, Content, and attributes from node to the calling element.
    void
    copyRef​(Xml copyFromNode)
    Changes this Xml object so that it references the same underlying XML element as copyFromNode.
    String
    decodeEntities​(String str)
    Decodes HTML character entities found in str and returns the decoded text.
    void
    decryptContent​(String password)
    Decrypts element content previously produced by EncryptContent, using the same password, and restores the original plaintext content.
    void
    encryptContent​(String password)
    Encrypts the calling element's text content using Chilkat's password-based 128-bit AES-CBC format and replaces the plaintext content with Base64-encoded encrypted data.
    Xml
    extractChildByIndex​(int index)
    Removes the direct child at zero-based index from the calling element and returns an Xml object for the detached child subtree.
    Xml
    extractChildByName​(String tagPath, String attrName, String attrValue)
    Finds, removes, and returns the first child selected by tagPath and the optional attribute criteria.
    Xml
    findChild​(String tagPath)
    Returns an Xml object referencing the child selected by tagPath.
    void
    findChild2​(String tagPath)
    Moves the calling Xml object's internal reference to the child selected by tagPath.
    Xml
    findNextRecord​(String tagPath, String contentPattern)
    Finds the next direct child record for which the descendant identified by tagPath has content matching contentPattern.
    Xml
    findOrAddNewChild​(String tagPath)
    Returns the child selected by tagPath if it already exists.
    Xml
    firstChild()
    Returns an Xml object referencing the first direct child of the calling element.
    boolean
    firstChild2()
    Moves the calling Xml object's internal reference to its first direct child.
    String
    getAttributeName​(int index)
    Returns the name of the attribute at zero-based index.
    String
    getAttributeValue​(int index)
    Returns the value of the attribute at zero-based index.
    int
    getAttributeValueInt​(int index)
    Returns the value of the attribute at zero-based index, interpreted as a 32-bit integer.
    String
    getAttrValue​(String name)
    Returns the value of the attribute named name on the calling element.
    int
    getAttrValueInt​(String name)
    Returns the value of the attribute named name interpreted as a 32-bit integer.
    boolean
    getCdata()
    Controls how this element's text content is emitted.
    Xml
    getChild​(int index)
    Returns an Xml object referencing the direct child at zero-based index.
    void
    getChild2​(int index)
    Moves the calling Xml object's internal reference to the direct child at zero-based index.
    String
    getChildAttrValue​(String tagPath, String attrName)
    Returns the value of attribute attrName on the descendant element selected by tagPath.
    boolean
    getChildBoolValue​(String tagPath)
    Returns the integer content of the child selected by tagPath as a Boolean value: content equal to 0 yields false; a non-zero integer yields true.
    String
    getChildContent​(String tagPath)
    Returns the text content of the child selected by tagPath.
    String
    getChildContentByIndex​(int index)
    Returns the text content of the direct child at zero-based index.
    void
    getChildContentSb​(String tagPath, StringBuilder sb)
    Finds the element selected by tagPath and appends that element's text content to sb.
    Xml
    getChildExact​(String tag, String content)
    Returns the first direct child whose tag equals tag and whose text content exactly equals content.
    int
    getChildIntValue​(String tagPath)
    Returns the content of the child selected by tagPath, interpreted as a 32-bit integer.
    String
    getChildTag​(int index)
    Returns the tag name of the direct child at zero-based index.
    String
    getChildTagByIndex​(int index)
    Returns the tag name of the direct child at zero-based index.
    Xml
    getChildWithAttr​(String tagPath, String attrName, String attrValue)
    Returns the child selected by tagPath that also has an attribute named attrName whose value exactly equals attrValue.
    Xml
    getChildWithContent​(String content)
    Returns the first direct child whose text content exactly equals content.
    Xml
    getChildWithTag​(String tagPath)
    Returns an Xml object referencing the child selected by tagPath.
    void
    getChildWithTag2​(String tagPath)
    Moves the calling Xml object's internal reference to the child selected by tagPath.
    String
    getContent()
    Gets or sets the text content stored directly on this XML element.
    int
    getContentInt()
    Gets or sets this element's content as a 32-bit integer.
    String
    getDocType()
    Gets or sets the document type declaration associated with the XML document.
    boolean
    getEmitBom()
    Controls whether a byte order mark (BOM, also called a preamble) is written when XML is saved to a file.
    boolean
    getEmitCompact()
    Controls whether XML emitted by GetXml and GetXmlSb is compact.
    boolean
    getEmitXmlDecl()
    Controls whether the XML declaration is included when XML is emitted.
    String
    getEncoding()
    Gets or sets the encoding value used in the XML declaration.
    int
    getI()
    Provides a substitution value for [i] in Chilkat tag paths and ChilkatPath expressions.
    boolean
    getIsBase64()
    Returns true if this element's content consists only of characters allowed in standard Base64 text, with whitespace ignored.
    int
    getJ()
    Provides a substitution value for [j] in Chilkat tag paths and ChilkatPath expressions.
    int
    getK()
    Provides a substitution value for [k] in Chilkat tag paths and ChilkatPath expressions.
    Xml
    getNthChildWithTag​(String tag, int n)
    Returns the zero-based nth direct child whose tag exactly equals tag.
    void
    getNthChildWithTag2​(String tag, int n)
    Moves the calling Xml object's internal reference to the zero-based nth direct child whose tag equals tag.
    int
    getNumAttributes()
    Returns the number of attributes on this element.
    int
    getNumChildren()
    Returns the number of direct child elements of this element.
    Xml
    getParent()
    Returns an Xml object referencing this element's parent.
    void
    getParent2()
    Moves the calling Xml object's internal reference to its parent.
    Xml
    getRoot()
    Returns an Xml object referencing the root element of the XML tree that contains the current element.
    void
    getRoot2()
    Moves the calling Xml object's internal reference to the root element of its XML tree.
    Xml
    getSelf()
    Returns a new Xml object that references the same underlying XML element as the calling object.
    boolean
    getSortCaseInsensitive()
    Controls case sensitivity for the XML sorting methods.
    boolean
    getStandalone()
    Controls the standalone pseudo-attribute in the XML declaration.
    boolean
    getStrict()
    When Strict is true, the XML loading methods first check that the input is well-formed XML.
    String
    getTag()
    Gets or sets the element name for this element, including any namespace prefix.
    String
    getTagNsPrefix()
    Gets or sets the namespace prefix portion of this element's tag.
    String
    getTagPath()
    Returns the Chilkat tag path needed to reach this element from the document root.
    String
    getTagUnprefixed()
    Gets or sets the unprefixed portion of this element's tag.
    int
    getTreeId()
    Returns the identifier of the XML tree to which this element belongs.
    String
    getUncommonOptions()
    Provides a catch-all string for uncommon XML behaviors.
    String
    getXml()
    Serializes the XML tree or subtree rooted at the current element and returns the XML text.
    void
    getXmlBd​(BinData bd)
    Serializes the XML tree or subtree rooted at the current element and appends the encoded XML bytes to bd.
    void
    getXmlSb​(StringBuilder sb)
    Serializes the XML tree or subtree rooted at the current element and appends the resulting XML text to sb.
    boolean
    hasAttribute​(String name)
    Returns true if the calling element has an attribute named name; otherwise returns false.
    boolean
    hasAttrWithValue​(String name, String value)
    Returns true if the calling element has an attribute named name whose value exactly equals value; otherwise returns false.
    boolean
    hasChildWithContent​(String content)
    Returns true if any direct child has text content exactly equal to content; otherwise returns false.
    boolean
    hasChildWithTag​(String tagPath)
    Returns true if the child selected by tagPath exists; otherwise returns false.
    boolean
    hasChildWithTagAndContent​(String tagPath, String content)
    Returns true if the child selected by tagPath exists and its text content exactly equals content; otherwise returns false.
    void
    insertChildTreeAfter​(int index, Xml tree)
    Inserts the entire subtree referenced by tree as a direct child immediately after the existing child at zero-based index.
    void
    insertChildTreeBefore​(int index, Xml tree)
    Inserts the entire subtree referenced by tree as a direct child immediately before the existing child at zero-based index.
    Xml
    lastChild()
    Returns an Xml object referencing the last direct child of the calling element.
    void
    lastChild2()
    Moves the calling Xml object's internal reference to its last direct child.
    void
    loadBd​(BinData bd, boolean autoTrim)
    Parses XML from the bytes contained in bd and replaces the calling object's current XML tree with the loaded document.
    void
    loadSb​(StringBuilder sb, boolean autoTrim)
    Parses XML from the current contents of sb and replaces the calling object's current XML tree with the loaded document.
    void
    loadXml​(String xmlData)
    Parses the XML text in xmlData and replaces the calling object's current XML tree content with the loaded document root.
    void
    loadXml2​(String xmlData, boolean autoTrim)
    Parses the XML text in xmlData and replaces the current XML tree, like LoadXml.
    void
    loadXmlFile​(String fileName)
    Reads and parses an XML document from fileName, replacing the calling object's current XML tree with the loaded document root.
    void
    loadXmlFile2​(String fileName, boolean autoTrim)
    Reads and parses an XML document from fileName, replacing the current XML tree.
    Xml
    newChild​(String tagPath, String content)
    Creates and returns a new child at tagPath with the specified text content.
    void
    newChild2​(String tagPath, String content)
    Creates a new child at tagPath with the specified text content, but does not return a separate Xml object for the new element.
    Xml
    newChildAfter​(int index, String tag, String content)
    Creates a new direct child with the specified tag and content, inserts it immediately after the child at zero-based index, and returns the new child element.
    Xml
    newChildBefore​(int index, String tag, String content)
    Creates a new direct child with the specified tag and content, inserts it immediately before the child at zero-based index, and returns the new child element.
    void
    newChildInt2​(String tagPath, int value)
    Creates a new child at tagPath whose content is the decimal representation of value.
    boolean
    nextInTraversal2​(StringBuilder sbState)
    Moves the calling Xml object to the next element in a depth-first traversal of the tree and updates sbState with the traversal state.
    Xml
    nextSibling()
    Returns an Xml object referencing the current element's next sibling, or no object when there is no next sibling.
    boolean
    nextSibling2()
    Moves the calling Xml object's internal reference to its next sibling.
    int
    numChildrenAt​(String tagPath)
    Returns the number of direct children of the element selected by tagPath.
    int
    numChildrenHavingTag​(String tag)
    Returns the number of direct children whose tag exactly equals tag.
    Xml
    previousSibling()
    Returns an Xml object referencing the current element's previous sibling, or no object when there is no previous sibling.
    void
    previousSibling2()
    Moves the calling Xml object's internal reference to its previous sibling.
    int
    pruneAttribute​(String attrName)
    Recursively traverses the subtree rooted at the calling element and removes every occurrence of the attribute named attrName.
    int
    pruneTag​(String tag)
    Recursively traverses the subtree rooted at the calling element and removes every element whose tag equals tag.
    void
    removeAllAttributes()
    Removes every attribute from the calling element.
    void
    removeAllChildren()
    Removes all direct child elements and their subtrees from the calling element.
    void
    removeAttribute​(String name)
    Removes the attribute named name from the calling element.
    void
    removeChild​(String tagPath)
    Removes all child elements selected by tagPath beneath the calling element.
    void
    removeChildByIndex​(int index)
    Removes the direct child at zero-based index, including that child's entire subtree.
    void
    removeChildWithContent​(String content)
    Removes all direct children whose text content exactly equals content, including each removed child's subtree.
    void
    removeFromTree()
    Detaches the calling element and its entire subtree from its parent.
    int
    removeStyleSheet​(String attrName, String attrValue)
    Removes XML stylesheet processing instructions whose attribute named attrName has the value attrValue.
    void
    saveBinaryContent​(String filename, boolean unzipFlag, boolean decryptFlag, String password)
    Decodes the binary content stored in this element and writes the resulting bytes to filename.
    void
    saveXml​(String fileName)
    Serializes the XML tree or subtree rooted at the current element and writes it to fileName.
    void
    scrub​(String directives)
    Recursively normalizes the XML subtree rooted at the calling element according to the comma-separated keywords in directives.
    Xml
    searchAllForContent​(Xml after, String contentPattern)
    Returns the first element whose text content matches contentPattern, regardless of tag name.
    void
    searchAllForContent2​(Xml after, String contentPattern)
    Performs the same breadth-first content search as SearchAllForContent, but moves the calling Xml object's internal reference to the matching element instead of returning a separate element object.
    Xml
    searchForAttribute​(Xml after, String tag, String attr, String valuePattern)
    Returns the first element whose tag equals tag, that has an attribute named attr, and whose attribute value matches valuePattern.
    void
    searchForAttribute2​(Xml after, String tag, String attr, String valuePattern)
    Performs the same breadth-first tag/attribute search as SearchForAttribute, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.
    Xml
    searchForContent​(Xml after, String tag, String contentPattern)
    Returns the first element whose tag equals tag and whose text content matches contentPattern.
    void
    searchForContent2​(Xml after, String tag, String contentPattern)
    Performs the same breadth-first tag/content search as SearchForContent, but moves the calling Xml object's internal reference to the matching element.
    Xml
    searchForTag​(Xml after, String tag)
    Returns the first element whose tag exactly equals tag.
    void
    searchForTag2​(Xml after, String tag)
    Performs the same breadth-first tag search as SearchForTag, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.
    void
    setBinaryContentBd​(BinData data, boolean zipFlag, boolean encryptFlag, String password)
    Stores the bytes in data as binary content on this element, with optional ZIP compression and optional password-based AES encryption.
    void
    setBinaryContentFromFile​(String filename, boolean zipFlag, boolean encryptFlag, String password)
    Reads the bytes from filename and stores them as this element's binary content, with optional ZIP compression and optional password-based encryption.
    void
    setCdata​(boolean value)
    Sets the Cdata property; see getCdata().
    void
    setContent​(String value)
    Sets the Content property; see getContent().
    void
    setContentInt​(int value)
    Sets the ContentInt property; see getContentInt().
    void
    setDocType​(String value)
    Sets the DocType property; see getDocType().
    void
    setEmitBom​(boolean value)
    Sets the EmitBom property; see getEmitBom().
    void
    setEmitCompact​(boolean value)
    Sets the EmitCompact property; see getEmitCompact().
    void
    setEmitXmlDecl​(boolean value)
    Sets the EmitXmlDecl property; see getEmitXmlDecl().
    void
    setEncoding​(String value)
    Sets the Encoding property; see getEncoding().
    void
    setI​(int value)
    Sets the I property; see getI().
    void
    setJ​(int value)
    Sets the J property; see getJ().
    void
    setK​(int value)
    Sets the K property; see getK().
    void
    setSortCaseInsensitive​(boolean value)
    Sets the SortCaseInsensitive property; see getSortCaseInsensitive().
    void
    setStandalone​(boolean value)
    Sets the Standalone property; see getStandalone().
    void
    setStrict​(boolean value)
    Sets the Strict property; see getStrict().
    void
    setTag​(String value)
    Sets the Tag property; see getTag().
    void
    setTagNsPrefix​(String value)
    Sets the TagNsPrefix property; see getTagNsPrefix().
    void
    setTagUnprefixed​(String value)
    Sets the TagUnprefixed property; see getTagUnprefixed().
    void
    setUncommonOptions​(String value)
    Sets the UncommonOptions property; see getUncommonOptions().
    void
    sortByAttribute​(String attrName, boolean ascending)
    Sorts the calling element's direct children by the string value of attribute attrName.
    void
    sortByAttributeInt​(String attrName, boolean ascending)
    Sorts the calling element's direct children numerically by the value of attribute attrName, interpreting each sort value as an integer rather than comparing the text lexicographically.
    void
    sortByContent​(boolean ascending)
    Sorts the calling element's direct children by their text content.
    void
    sortByTag​(boolean ascending)
    Sorts the calling element's direct children by tag name.
    void
    sortRecordsByAttribute​(String sortTag, String attrName, boolean ascending)
    Treats each direct child as a record and sorts those records by the value of attribute attrName on the record's child identified by sortTag.
    void
    sortRecordsByContent​(String sortTag, boolean ascending)
    Treats each direct child as a record and sorts those records by the text content of the record's child named sortTag.
    void
    sortRecordsByContentInt​(String sortTag, boolean ascending)
    Treats each direct child as a record and sorts those records numerically by the integer content of the record's child named sortTag.
    void
    swapNode​(Xml node)
    Swaps the calling element's tag, text content, and attributes with those of node.
    void
    swapTree​(Xml tree)
    Swaps the calling element's complete tree state with tree, including tag, text content, attributes, and children.
    String
    tagContent​(String tagName)
    Searches the subtree rooted at the calling element for the first element whose tag equals tagName and returns that element's text content.
    boolean
    tagEquals​(String tag)
    Returns true if the calling element's complete tag name, including any namespace prefix, exactly equals tag; otherwise returns false.
    int
    tagIndex​(String tagPath)
    Returns the zero-based child index of the element selected by tagPath.
    boolean
    tagNsEquals​(String ns)
    Returns true if this element's namespace-prefix portion exactly equals ns; otherwise returns false.
    boolean
    tagUnpEquals​(String unprefixedTag)
    Returns true if this element's unprefixed tag exactly equals unprefixedTag; otherwise returns false.
    void
    unzipContent()
    Reverses ZipContent: decodes and decompresses the calling element's compressed content and replaces the stored Base64-compressed representation with the original content.
    void
    unzipTree()
    Reverses ZipTree: decompresses the stored representation and reconstructs the calling element's previously compressed subtree.
    void
    updateAt​(String tagPath, boolean autoCreate, String value)
    Sets the text content of the element selected by tagPath to value.
    void
    updateAttrAt​(String tagPath, boolean autoCreate, String attrName, String attrValue)
    Sets attribute attrName to attrValue on the element selected by tagPath.
    void
    updateAttribute​(String attrName, String attrValue)
    Sets attribute attrName to attrValue.
    void
    updateAttributeInt​(String attrName, int value)
    Sets attribute attrName to the decimal representation of integer value.
    void
    updateChildContent​(String tagPath, String value)
    Sets the text content of the child selected by tagPath to value.
    void
    updateChildContentInt​(String tagPath, int value)
    Sets the content of the child selected by tagPath to the decimal representation of integer value.
    void
    zipContent()
    ZIP-compresses this element's text content and replaces the original content with Base64-encoded compressed data.
    void
    zipTree()
    ZIP-compresses the calling element's content together with its entire child subtree and replaces that structure with Base64-encoded compressed data.

    Methods inherited from class com.chilkatsoft.chilkat2.ChilkatObject

    close, getDebugLogFilePath, getLastErrorHtml, getLastErrorText, getLastErrorXml, getLastMethodSuccess, getVerboseLogging, getVersion, isClosed, setDebugLogFilePath, setLastMethodSuccess, setVerboseLogging, toString

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Xml

      public Xml()
      Creates a new Xml object.

  • Method Details

    • getCdata

      public boolean getCdata()
      Controls how this element's text content is emitted. When set to true, the element content is written inside a CDATA section instead of being emitted as ordinary character data with XML escaping. CDATA and escaping: CDATA is useful when text contains many characters such as < or &. It does not change the logical text value of the element; it only changes how that text is represented in the serialized XML.
      Returns:
      the value of the Cdata property

    • setCdata

      public void setCdata​(boolean value)
      Sets the Cdata property; see getCdata().
      Parameters:
      value - the new value

    • getContent

      public String getContent()
      Gets or sets the text content stored directly on this XML element. Child elements are not included in this value.

      For example, both of the following elements have This is the content as their Content: 

      _LT_tag1_GT_This is the content_LT_/tag1_GT_
 
 _LT_tag2_GT__LT_child1_GT_abc_LT_/child1_GT__LT_child2_GT_abc_LT_/child2_GT_This is the content_LT_/tag2_GT_

      Content vs. children: Chilkat stores an element's direct text content separately from its child elements. Use the child-navigation methods when you need the nested elements themselves.

      Returns:
      the value of the Content property

    • setContent

      public void setContent​(String value)
      Sets the Content property; see getContent().
      Parameters:
      value - the new value (not null)

    • getContentInt

      public int getContentInt()
      Gets or sets this element's content as a 32-bit integer. Setting the property converts the integer to its decimal text representation; getting the property interprets the element's text content as an integer. Numeric content: Use Content when the value may exceed the range of a 32-bit integer or when the exact lexical representation must be preserved.
      Returns:
      the value of the ContentInt property

    • setContentInt

      public void setContentInt​(int value)
      Sets the ContentInt property; see getContentInt().
      Parameters:
      value - the new value

    • getDocType

      public String getDocType()
      Gets or sets the document type declaration associated with the XML document.

      The value represents the document-level DOCTYPE declaration, for example _LT_!DOCTYPE note SYSTEM "note.dtd"_GT_.

      Document-level setting: Although this property may be accessed from any element reference in the tree, the DOCTYPE belongs to the XML document as a whole rather than to an individual element.

      Returns:
      the value of the DocType property

    • setDocType

      public void setDocType​(String value)
      Sets the DocType property; see getDocType().
      Parameters:
      value - the new value (not null)

    • getEmitBom

      public boolean getEmitBom()
      Controls whether a byte order mark (BOM, also called a preamble) is written when XML is saved to a file. The default is false.

      This setting is relevant to encodings for which a BOM can be emitted, such as UTF-8 and UTF-16. It does not affect XML returned as a language string by methods such as GetXml.

      Returns:
      the value of the EmitBom property

    • setEmitBom

      public void setEmitBom​(boolean value)
      Sets the EmitBom property; see getEmitBom().
      Parameters:
      value - the new value

    • getEmitCompact

      public boolean getEmitCompact()
      Controls whether XML emitted by GetXml and GetXmlSb is compact. When true, unnecessary formatting whitespace and line breaks are omitted. The default is false for backward compatibility. Formatting only: Compact output changes presentation, not the XML tree or its element content.
      Returns:
      the value of the EmitCompact property

    • setEmitCompact

      public void setEmitCompact​(boolean value)
      Sets the EmitCompact property; see getEmitCompact().
      Parameters:
      value - the new value

    • getEmitXmlDecl

      public boolean getEmitXmlDecl()
      Controls whether the XML declaration is included when XML is emitted. The default is true. When set to false, output methods such as GetXml and SaveXml omit the declaration.

      An XML declaration is the leading construct such as _LT_?xml version="1.0" encoding="utf-8"?_GT_.

      Returns:
      the value of the EmitXmlDecl property

    • setEmitXmlDecl

      public void setEmitXmlDecl​(boolean value)
      Sets the EmitXmlDecl property; see getEmitXmlDecl().
      Parameters:
      value - the new value

    • getEncoding

      public String getEncoding()
      Gets or sets the encoding value used in the XML declaration. The default is utf-8. This is a document-level setting and may be accessed from any element in the tree.

      When XML is loaded, Chilkat sets this property from the encoding declared by the input XML when one is present. If no encoding is declared, the property is reset to utf-8.

      Important: Changing Encoding changes the declared/output encoding used when XML is serialized; it does not reinterpret or transcode the already-stored Unicode text inside the in-memory tree.

      Returns:
      the value of the Encoding property

    • setEncoding

      public void setEncoding​(String value)
      Sets the Encoding property; see getEncoding().
      Parameters:
      value - the new value (not null)

    • getI

      public int getI()
      Provides a substitution value for [i] in Chilkat tag paths and ChilkatPath expressions. When a path contains [i], the current value of this property is substituted for I. Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.
      Returns:
      the value of the I property

    • setI

      public void setI​(int value)
      Sets the I property; see getI().
      Parameters:
      value - the new value

    • getIsBase64

      public boolean getIsBase64()
      Returns true if this element's content consists only of characters allowed in standard Base64 text, with whitespace ignored. Standard Base64 uses A-Z, a-z, 0-9, +, /, and optional trailing = padding. Syntax check, not semantic validation: A value can contain only Base64 characters and still not represent the data your application expects. This property is useful as a quick content-format test.
      Returns:
      the value of the IsBase64 property (read-only)

    • getJ

      public int getJ()
      Provides a substitution value for [j] in Chilkat tag paths and ChilkatPath expressions. When a path contains [j], the current value of this property is substituted for J. Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.
      Returns:
      the value of the J property

    • setJ

      public void setJ​(int value)
      Sets the J property; see getJ().
      Parameters:
      value - the new value

    • getK

      public int getK()
      Provides a substitution value for [k] in Chilkat tag paths and ChilkatPath expressions. When a path contains [k], the current value of this property is substituted for K. Loop-friendly paths: The I, J, and K properties make it convenient to reuse a path expression inside nested loops without constructing a new path string for every index.
      Returns:
      the value of the K property

    • setK

      public void setK​(int value)
      Sets the K property; see getK().
      Parameters:
      value - the new value

    • getNumAttributes

      public int getNumAttributes()
      Returns the number of attributes on this element.

      For example, _LT_tag attr1="value1" attr2="value2"_GT_..._LT_/tag_GT_ has two attributes. Attribute indexes used by methods such as GetAttributeName and GetAttributeValue are zero-based.

      Returns:
      the value of the NumAttributes property (read-only)

    • getNumChildren

      public int getNumChildren()
      Returns the number of direct child elements of this element. Descendants below those children are not included in the count. Direct children only: Use traversal or search methods when you need to inspect the entire subtree rather than only the immediate children.
      Returns:
      the value of the NumChildren property (read-only)

    • getSortCaseInsensitive

      public boolean getSortCaseInsensitive()
      Controls case sensitivity for the XML sorting methods. Set to true for case-insensitive string comparisons or false for case-sensitive comparisons.
      Returns:
      the value of the SortCaseInsensitive property

    • setSortCaseInsensitive

      public void setSortCaseInsensitive​(boolean value)
      Sets the SortCaseInsensitive property; see getSortCaseInsensitive().
      Parameters:
      value - the new value

    • getStandalone

      public boolean getStandalone()
      Controls the standalone pseudo-attribute in the XML declaration. This is a document-level setting and may be accessed from any element in the tree.

      Setting this property to true causes the declaration to include standalone="yes".

      XML declaration: The standalone declaration concerns whether the document relies on external markup declarations. It is metadata in the XML declaration; it does not by itself validate or alter the document.

      Returns:
      the value of the Standalone property

    • setStandalone

      public void setStandalone​(boolean value)
      Sets the Standalone property; see getStandalone().
      Parameters:
      value - the new value

    • getStrict

      public boolean getStrict()
      When Strict is true, the XML loading methods first check that the input is well-formed XML. If it is not, the load fails and the contents of this Xml object are left unchanged. The default is false.

      This applies to loadXml(String), loadXml2(String, boolean), loadSb(StringBuilder, boolean), loadBd(BinData, boolean), loadXmlFile(String) and loadXmlFile2(String, boolean).

      Chilkat's XML parser is deliberately tolerant. By default it can accept input that is not well-formed, succeed, and leave a partially populated tree. That is convenient when the goal is a best-effort parse of imperfect input, but it is the wrong behavior when a silently dropped element or attribute changes what the application does.

      Set Strict to true for XML carrying configuration, credentials, signed content, or security parameters, where an element that quietly failed to load would be acted on as though it had never been present.

      The check is for XML 1.0 well-formedness only. It is not a validating parse: no DTD or schema is read, and the document is not checked against one. Markup declarations inside an internal DTD subset are skipped rather than parsed.

      Note: The default is false so that existing applications are unaffected. When a strict load is rejected, this Xml object keeps whatever it held before the call, so a failed reload never leaves the object empty.

      Returns:
      the value of the Strict property

    • setStrict

      public void setStrict​(boolean value)
      Sets the Strict property; see getStrict().
      Parameters:
      value - the new value

    • getTag

      public String getTag()
      Gets or sets the element name for this element, including any namespace prefix. For example, the tag for _LT_soapenv:Body_GT_ is soapenv:Body.

      Use TagNsPrefix and TagUnprefixed when the prefix and local portion are needed separately.

      Returns:
      the value of the Tag property

    • setTag

      public void setTag​(String value)
      Sets the Tag property; see getTag().
      Parameters:
      value - the new value (not null)

    • getTagNsPrefix

      public String getTagNsPrefix()
      Gets or sets the namespace prefix portion of this element's tag. For soapenv:Envelope, the namespace prefix is soapenv. Prefix vs. namespace URI: This property deals with the lexical prefix in the tag name. A prefix is not itself the namespace URI; namespace bindings are expressed through xmlns attributes in the XML.
      Returns:
      the value of the TagNsPrefix property

    • setTagNsPrefix

      public void setTagNsPrefix​(String value)
      Sets the TagNsPrefix property; see getTagNsPrefix().
      Parameters:
      value - the new value (not null)

    • getTagPath

      public String getTagPath()
      Returns the Chilkat tag path needed to reach this element from the document root. If this object currently references the root element, the returned path is the empty string. Not XPath: A Chilkat tag path is Chilkat's own navigation syntax, typically using | between element names. It is not an XPath expression.
      Returns:
      the value of the TagPath property (read-only)

    • getTagUnprefixed

      public String getTagUnprefixed()
      Gets or sets the unprefixed portion of this element's tag. For soapenv:Envelope, the unprefixed tag is Envelope.

      Use TagNsPrefix to access the prefix separately.

      Returns:
      the value of the TagUnprefixed property

    • setTagUnprefixed

      public void setTagUnprefixed​(String value)
      Sets the TagUnprefixed property; see getTagUnprefixed().
      Parameters:
      value - the new value (not null)

    • getTreeId

      public int getTreeId()
      Returns the identifier of the XML tree to which this element belongs. Elements in the same XML document have the same TreeId. Useful for element references: Multiple Xml objects can reference different elements in the same underlying tree. Comparing TreeId values is a convenient way to determine whether two element references belong to that same tree.
      Returns:
      the value of the TreeId property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a catch-all string for uncommon XML behaviors. The default is the empty string, which is appropriate for normal use.

      Leave this property empty unless Chilkat documentation or support identifies a specific option needed for a specialized interoperability case.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • accumulateTagContent

      public String accumulateTagContent​(String tag, String skipTags)
      Traverses the subtree rooted at the calling element and concatenates the text content of all elements whose tag equals tag.

      skipTags is a vertical-bar-delimited list of tag names whose entire subtrees are excluded from the accumulation. For example, script|style skips elements rooted at either of those tags.

      Parameters:
      tag - the tag argument (not null)
      skipTags - the skipTags argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addAttribute

      public void addAttribute​(String name, String value)
      Adds an attribute named name with the specified string value to the calling element.

      Returns true on success and false on failure.

      When an attribute may already exist: Use AddOrUpdateAttribute or UpdateAttribute when the desired behavior is to update an existing attribute value instead of requiring a new attribute.

      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addAttributeInt

      public void addAttributeInt​(String name, int value)
      Adds an attribute named name whose value is the decimal representation of value.

      Returns true on success and false on failure.

      Parameters:
      name - the name argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addChildTree

      public void addChildTree​(Xml tree)
      Adds the entire XML subtree referenced by tree as a new direct child of the calling element.

      If tree already belongs to another XML document, the subtree is transferred to the destination tree rather than copied as an unrelated duplicate.

      Tree ownership: After moving a subtree between documents, its elements belong to the destination tree. TreeId can be used to determine which tree an element reference belongs to.

      Parameters:
      tree - the tree argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addOrUpdateAttribute

      public void addOrUpdateAttribute​(String name, String value)
      Sets the string value of an attribute on the calling element. If an attribute named name already exists, its value is replaced; otherwise the attribute is added.
      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)

    • addOrUpdateAttributeI

      public void addOrUpdateAttributeI​(String name, int value)
      Sets an integer-valued attribute on the calling element. If an attribute named name already exists, its value is replaced with the decimal representation of value; otherwise the attribute is added.
      Parameters:
      name - the name argument (not null)
      value - the value argument

    • addStyleSheet

      public void addStyleSheet​(String styleSheet)
      Adds an XML stylesheet processing instruction to the document. Pass the complete processing-instruction text, for example: 
      _LT_?xml-stylesheet href="mystyle.css" title="Compact" type="text/css"?_GT_

      Processing instruction: An XML stylesheet declaration associates stylesheet metadata with the XML document; it does not apply or execute the stylesheet.

      Parameters:
      styleSheet - the styleSheet argument (not null)

    • addToAttribute

      public void addToAttribute​(String name, int amount)
      Treats the named attribute value as an integer, adds amount, and stores the resulting integer back in the attribute.

      If the attribute does not yet exist, this method behaves like AddOrUpdateAttributeI and creates it with amount as the value.

      Parameters:
      name - the name argument (not null)
      amount - the amount argument

    • addToChildContent

      public void addToChildContent​(String tag, int amount)
      Finds the child identified by tag, interprets its content as an integer, adds amount, and stores the resulting integer as the child's new content.
      Parameters:
      tag - the tag argument (not null)
      amount - the amount argument

    • addToContent

      public void addToContent​(int amount)
      Interprets this element's content as an integer, adds amount, and stores the resulting integer as the new content.
      Parameters:
      amount - the amount argument

    • appendToContent

      public void appendToContent​(String str)
      Appends str to the existing text content of the calling element without replacing its child elements.

      Returns true on success and false on failure.

      Parameters:
      str - the str argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • childContentMatches

      public boolean childContentMatches​(String tagPath, String pattern, boolean caseSensitive)
      Returns true if the child identified by tagPath has content matching pattern; otherwise returns false. caseSensitive controls whether letter case is significant.

      The pattern may contain * wildcards, where each asterisk matches zero or more characters.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Parameters:
      tagPath - the tagPath argument (not null)
      pattern - the pattern argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • chilkatPath

      public String chilkatPath​(String pathCmd)
      Evaluates a Chilkat-specific path command that can navigate from the current element, return element content or an attribute value, or move the caller's internal element reference.

      This syntax is not XPath. Commands are separated by vertical bars and the expression ends with a return command: 

      command|command|command|...|returnCommand

      Navigation commands include:

      • TagName - first direct child having that tag.
      • TagName[n] - the indexed direct child having that tag.
      • .. - parent.
      • ++ / -- - next / previous sibling.
      • TagName{Content} - first direct child with that tag and exact content.
      • /T/TagName - traverse the subtree and find the first element with that tag.
      • /C/TagName,ContentPattern - traverse for a tag whose content matches a wildcard pattern.
      • /C/ContentPattern - traverse for any tag whose content matches a wildcard pattern.
      • /A/TagName,AttrName,AttrValuePattern - traverse for a tag having a matching attribute value.

      The final return command is:

      • * - return the current element's content.
      • (AttrName) - return an attribute value.
      • $ - move this Xml object to the selected element and return an empty string.

      Index substitution: The I, J, and K properties can be used with [i], [j], and [k] in path expressions.

      Parameters:
      pathCmd - the pathCmd argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • clear

      public void clear()
      Clears the calling element by removing all child elements, attributes, and text content, and resets its tag name to unnamed.

      The element itself remains in the tree; this method clears its contents rather than removing the element from its parent.

    • contentMatches

      public boolean contentMatches​(String pattern, boolean caseSensitive)
      Returns true if this element's content matches pattern; otherwise returns false. caseSensitive controls whether letter case is significant.

      The pattern may contain * wildcards, where each asterisk matches zero or more characters.

      Parameters:
      pattern - the pattern argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • copy

      public void copy​(Xml node)
      Copies the Tag, Content, and attributes from node to the calling element. Not a subtree copy: This method does not copy the source element's children. Use a tree-oriented method such as AddChildTree or SwapTree when child structure is part of the operation.
      Parameters:
      node - the node argument (not null)

    • copyRef

      public void copyRef​(Xml copyFromNode)
      Changes this Xml object so that it references the same underlying XML element as copyFromNode. The caller's previous element reference is discarded. Reference operation: CopyRef does not copy XML data. After the call, both Xml objects refer to the same element, so edits through either reference affect the same tree element.
      Parameters:
      copyFromNode - the copyFromNode argument (not null)

    • decodeEntities

      public String decodeEntities​(String str)
      Decodes HTML character entities found in str and returns the decoded text. This is a utility operation; it does not modify the XML tree unless the returned string is assigned to an element.

      For example, an HTML entity such as &amp; is decoded to &.

      Parameters:
      str - the str argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • decryptContent

      public void decryptContent​(String password)
      Decrypts element content previously produced by EncryptContent, using the same password, and restores the original plaintext content.

      Returns true on success and false on failure.

      Compatibility-oriented encryption: This method is paired specifically with EncryptContent. It is not a general XML Encryption (XML-Enc) implementation.

      Parameters:
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • encryptContent

      public void encryptContent​(String password)
      Encrypts the calling element's text content using Chilkat's password-based 128-bit AES-CBC format and replaces the plaintext content with Base64-encoded encrypted data.

      Returns true on success and false on failure.

      Scope: Only this element's content is encrypted. The tag, attributes, and child elements are not encrypted by this method. Use DecryptContent with the same password to restore the content.

      Parameters:
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • extractChildByIndex

      public Xml extractChildByIndex​(int index)
      Removes the direct child at zero-based index from the calling element and returns an Xml object for the detached child subtree. Extract vs. remove: Unlike RemoveChildByIndex, extraction gives the caller a reference to the removed subtree so it can be retained, inspected, or attached elsewhere.
      Parameters:
      index - the index argument
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • extractChildByName

      public Xml extractChildByName​(String tagPath, String attrName, String attrValue)
      Finds, removes, and returns the first child selected by tagPath and the optional attribute criteria.

      If attrName and attrValue are empty, the first child matching the tag/path is extracted. If attrName is provided, the child must have that attribute. If attrValue is also provided, the attribute value must match exactly.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Parameters:
      tagPath - the tagPath argument (not null)
      attrName - the attrName argument (not null)
      attrValue - the attrValue argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • findChild

      public Xml findChild​(String tagPath)
      Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • findChild2

      public void findChild2​(String tagPath)
      Moves the calling Xml object's internal reference to the child selected by tagPath. Returns true when the child is found and the move succeeds; otherwise returns false. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      tagPath - the tagPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • findNextRecord

      public Xml findNextRecord​(String tagPath, String contentPattern)
      Finds the next direct child record for which the descendant identified by tagPath has content matching contentPattern. This is intended for iterating record-like child elements.

      The content pattern may contain * wildcards.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Parameters:
      tagPath - the tagPath argument (not null)
      contentPattern - the contentPattern argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • findOrAddNewChild

      public Xml findOrAddNewChild​(String tagPath)
      Returns the child selected by tagPath if it already exists. If it does not exist, creates the required child path with empty content and returns the resulting child element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Use NewChild instead when duplicate children with the same tag are intentional.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • firstChild

      public Xml firstChild()
      Returns an Xml object referencing the first direct child of the calling element.

      A common forward-iteration pattern is FirstChild followed by repeated calls to NextSibling.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • firstChild2

      public boolean firstChild2()
      Moves the calling Xml object's internal reference to its first direct child. Returns true if a first child exists; otherwise returns false. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      the result; this method never throws ChilkatException

    • getAttrValue

      public String getAttrValue​(String name)
      Returns the value of the attribute named name on the calling element.

      Use HasAttribute when the application must distinguish a missing attribute from an attribute whose value is empty.

      Parameters:
      name - the name argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getAttrValueInt

      public int getAttrValueInt​(String name)
      Returns the value of the attribute named name interpreted as a 32-bit integer. Returns 0 if the attribute does not exist. Ambiguous zero: Because a missing attribute and an attribute containing zero can both yield 0, call HasAttribute first when that distinction matters.
      Parameters:
      name - the name argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getAttributeName

      public String getAttributeName​(int index)
      Returns the name of the attribute at zero-based index. Use NumAttributes to determine the valid index range.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAttributeValue

      public String getAttributeValue​(int index)
      Returns the value of the attribute at zero-based index. Use NumAttributes to determine the valid index range.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getAttributeValueInt

      public int getAttributeValueInt​(int index)
      Returns the value of the attribute at zero-based index, interpreted as a 32-bit integer.
      Parameters:
      index - the index argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getChild

      public Xml getChild​(int index)
      Returns an Xml object referencing the direct child at zero-based index. The calling object remains positioned on its current element.

      Use NumChildren to determine the valid child range.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Parameters:
      index - the index argument
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChild2

      public void getChild2​(int index)
      Moves the calling Xml object's internal reference to the direct child at zero-based index. Returns true on success and false if the child cannot be selected. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      index - the index argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChildAttrValue

      public String getChildAttrValue​(String tagPath, String attrName)
      Returns the value of attribute attrName on the descendant element selected by tagPath. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      attrName - the attrName argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getChildBoolValue

      public boolean getChildBoolValue​(String tagPath)
      Returns the integer content of the child selected by tagPath as a Boolean value: content equal to 0 yields false; a non-zero integer yields true. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • getChildContent

      public String getChildContent​(String tagPath)
      Returns the text content of the child selected by tagPath. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Content only: The returned value is the child element's direct Content; nested child elements are not serialized into this string.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getChildContentByIndex

      public String getChildContentByIndex​(int index)
      Returns the text content of the direct child at zero-based index. Use NumChildren to determine the valid range.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChildContentSb

      public void getChildContentSb​(String tagPath, StringBuilder sb)
      Finds the element selected by tagPath and appends that element's text content to sb.

      The existing contents of the StringBuilder are preserved.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Returns true on success and false on failure.

      Parameters:
      tagPath - the tagPath argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChildExact

      public Xml getChildExact​(String tag, String content)
      Returns the first direct child whose tag equals tag and whose text content exactly equals content.

      The calling object remains positioned on its current element.

      Parameters:
      tag - the tag argument (not null)
      content - the content argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getChildIntValue

      public int getChildIntValue​(String tagPath)
      Returns the content of the child selected by tagPath, interpreted as a 32-bit integer. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Integer range: Use GetChildContent and parse the returned text separately when values may exceed the range of a 32-bit integer.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getChildTag

      public String getChildTag​(int index)
      Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChildTagByIndex

      public String getChildTagByIndex​(int index)
      Returns the tag name of the direct child at zero-based index. Use NumChildren to determine the valid index range.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getChildWithAttr

      public Xml getChildWithAttr​(String tagPath, String attrName, String attrValue)
      Returns the child selected by tagPath that also has an attribute named attrName whose value exactly equals attrValue. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      attrName - the attrName argument (not null)
      attrValue - the attrValue argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getChildWithContent

      public Xml getChildWithContent​(String content)
      Returns the first direct child whose text content exactly equals content. The child tag may be any value.
      Parameters:
      content - the content argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getChildWithTag

      public Xml getChildWithTag​(String tagPath)
      Returns an Xml object referencing the child selected by tagPath. The calling object remains positioned on its current element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getChildWithTag2

      public void getChildWithTag2​(String tagPath)
      Moves the calling Xml object's internal reference to the child selected by tagPath. Returns true when the child is found and the move succeeds; otherwise returns false. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      tagPath - the tagPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getNthChildWithTag

      public Xml getNthChildWithTag​(String tag, int n)
      Returns the zero-based nth direct child whose tag exactly equals tag. Children with other tag names are ignored when counting matches.

      Use NumChildrenHavingTag to determine how many matching children are available.

      Parameters:
      tag - the tag argument (not null)
      n - the n argument
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getNthChildWithTag2

      public void getNthChildWithTag2​(String tag, int n)
      Moves the calling Xml object's internal reference to the zero-based nth direct child whose tag equals tag. Returns true on success and false when no such child exists. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Parameters:
      tag - the tag argument (not null)
      n - the n argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getParent

      public Xml getParent()
      Returns an Xml object referencing this element's parent. Returns no parent when the current element is the document root. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • getParent2

      public void getParent2()
      Moves the calling Xml object's internal reference to its parent. Returns true if a parent exists; otherwise returns false when already at the root. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getRoot

      public Xml getRoot()
      Returns an Xml object referencing the root element of the XML tree that contains the current element. The calling object remains positioned on its current element. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getRoot2

      public void getRoot2()
      Moves the calling Xml object's internal reference to the root element of its XML tree. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

    • getSelf

      public Xml getSelf()
      Returns a new Xml object that references the same underlying XML element as the calling object. Shared element reference: This is not a deep copy. Both objects reference the same element, so changes made through either object are changes to the same XML tree.
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getXml

      public String getXml()
      Serializes the XML tree or subtree rooted at the current element and returns the XML text.

      When called while positioned on the document root, the XML declaration is included if EmitXmlDecl is true. When called on a non-root element, only that subtree is emitted and the document declaration is not included.

      EmitCompact, Encoding, Standalone, and related document/output properties affect serialization as applicable.

      String vs. bytes: A language string is Unicode text. The Encoding declaration describes serialized XML encoding, while actual byte encoding matters when XML is written to a file or byte-oriented destination.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getXmlBd

      public void getXmlBd​(BinData bd)
      Serializes the XML tree or subtree rooted at the current element and appends the encoded XML bytes to bd.

      The existing contents of the BinData object are preserved. The XML output encoding is governed by the XML document's output settings, including Encoding.

      Returns true on success and false on failure.

      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getXmlSb

      public void getXmlSb​(StringBuilder sb)
      Serializes the XML tree or subtree rooted at the current element and appends the resulting XML text to sb.

      The existing contents of sb are preserved. Output properties such as EmitCompact and EmitXmlDecl apply as appropriate.

      Returns true on success and false on failure.

      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasAttrWithValue

      public boolean hasAttrWithValue​(String name, String value)
      Returns true if the calling element has an attribute named name whose value exactly equals value; otherwise returns false.
      Parameters:
      name - the name argument (not null)
      value - the value argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • hasAttribute

      public boolean hasAttribute​(String name)
      Returns true if the calling element has an attribute named name; otherwise returns false.
      Parameters:
      name - the name argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • hasChildWithContent

      public boolean hasChildWithContent​(String content)
      Returns true if any direct child has text content exactly equal to content; otherwise returns false.
      Parameters:
      content - the content argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • hasChildWithTag

      public boolean hasChildWithTag​(String tagPath)
      Returns true if the child selected by tagPath exists; otherwise returns false. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • hasChildWithTagAndContent

      public boolean hasChildWithTagAndContent​(String tagPath, String content)
      Returns true if the child selected by tagPath exists and its text content exactly equals content; otherwise returns false. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      content - the content argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • insertChildTreeAfter

      public void insertChildTreeAfter​(int index, Xml tree)
      Inserts the entire subtree referenced by tree as a direct child immediately after the existing child at zero-based index.

      If tree belongs to another XML document, the subtree is transferred to the destination tree.

      Structural move: The operation preserves the subtree structure. The supplied tree is not flattened into text content.

      Parameters:
      index - the index argument
      tree - the tree argument (not null)

    • insertChildTreeBefore

      public void insertChildTreeBefore​(int index, Xml tree)
      Inserts the entire subtree referenced by tree as a direct child immediately before the existing child at zero-based index.

      If tree belongs to another XML document, the subtree is transferred to the destination tree.

      Structural move: The operation preserves the subtree structure. The supplied tree is not flattened into text content.

      Parameters:
      index - the index argument
      tree - the tree argument (not null)

    • lastChild

      public Xml lastChild()
      Returns an Xml object referencing the last direct child of the calling element.

      A common reverse-iteration pattern is LastChild followed by repeated calls to PreviousSibling.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • lastChild2

      public void lastChild2()
      Moves the calling Xml object's internal reference to its last direct child. Returns true if a last child exists; otherwise returns false. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadBd

      public void loadBd​(BinData bd, boolean autoTrim)
      Parses XML from the bytes contained in bd and replaces the calling object's current XML tree with the loaded document.

      If autoTrim is true, leading and trailing whitespace is removed from each leaf element's text content during loading.

      Returns true on success and false on failure.

      Parameters:
      bd - the bd argument (not null)
      autoTrim - the autoTrim argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadSb

      public void loadSb​(StringBuilder sb, boolean autoTrim)
      Parses XML from the current contents of sb and replaces the calling object's current XML tree with the loaded document.

      If autoTrim is true, leading and trailing whitespace is removed from each leaf element's text content while loading.

      Returns true on success and false on failure.

      Parameters:
      sb - the sb argument (not null)
      autoTrim - the autoTrim argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadXml

      public void loadXml​(String xmlData)
      Parses the XML text in xmlData and replaces the calling object's current XML tree content with the loaded document root. Returns true if parsing succeeds. Replacement operation: A successful load replaces the current document/tree state represented by this object; it does not append the loaded XML beneath the current element.
      Parameters:
      xmlData - the xmlData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadXml2

      public void loadXml2​(String xmlData, boolean autoTrim)
      Parses the XML text in xmlData and replaces the current XML tree, like LoadXml. The autoTrim argument additionally controls whether leading and trailing whitespace is removed from each leaf element's text content while loading. Whitespace significance: Set autoTrim to false when leading or trailing text whitespace is significant to the application.
      Parameters:
      xmlData - the xmlData argument (not null)
      autoTrim - the autoTrim argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadXmlFile

      public void loadXmlFile​(String fileName)
      Reads and parses an XML document from fileName, replacing the calling object's current XML tree with the loaded document root. Returns true on success.

      The file's XML declaration and byte encoding are used as part of normal XML parsing.

      Parameters:
      fileName - the fileName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadXmlFile2

      public void loadXmlFile2​(String fileName, boolean autoTrim)
      Reads and parses an XML document from fileName, replacing the current XML tree. The autoTrim argument controls whether leading and trailing whitespace is removed from each leaf element's text content. Whitespace significance: Set autoTrim to false when leading or trailing text whitespace must be preserved exactly.
      Parameters:
      fileName - the fileName argument (not null)
      autoTrim - the autoTrim argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newChild

      public Xml newChild​(String tagPath, String content)
      Creates and returns a new child at tagPath with the specified text content. A new child is created even when a child with the same tag already exists. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed. Use FindOrAddNewChild when duplicate final children should be avoided.
      Parameters:
      tagPath - the tagPath argument (not null)
      content - the content argument (not null)
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newChild2

      public void newChild2​(String tagPath, String content)
      Creates a new child at tagPath with the specified text content, but does not return a separate Xml object for the new element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.
      Parameters:
      tagPath - the tagPath argument (not null)
      content - the content argument (not null)

    • newChildAfter

      public Xml newChildAfter​(int index, String tag, String content)
      Creates a new direct child with the specified tag and content, inserts it immediately after the child at zero-based index, and returns the new child element.
      Parameters:
      index - the index argument
      tag - the tag argument (not null)
      content - the content argument (not null)
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newChildBefore

      public Xml newChildBefore​(int index, String tag, String content)
      Creates a new direct child with the specified tag and content, inserts it immediately before the child at zero-based index, and returns the new child element.
      Parameters:
      index - the index argument
      tag - the tag argument (not null)
      content - the content argument (not null)
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newChildInt2

      public void newChildInt2​(String tagPath, int value)
      Creates a new child at tagPath whose content is the decimal representation of value. No separate child object is returned. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Intermediate elements in a multi-part path are created as needed.
      Parameters:
      tagPath - the tagPath argument (not null)
      value - the value argument

    • nextInTraversal2

      public boolean nextInTraversal2​(StringBuilder sbState)
      Moves the calling Xml object to the next element in a depth-first traversal of the tree and updates sbState with the traversal state.

      Pass an empty StringBuilder when beginning a traversal, then reuse the same sbState for each subsequent call.

      Why the name ends in 2: This method changes the caller's internal element reference. There is no separate NextInTraversal method that returns another Xml object.

      Parameters:
      sbState - the sbState argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • nextSibling

      public Xml nextSibling()
      Returns an Xml object referencing the current element's next sibling, or no object when there is no next sibling. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • nextSibling2

      public boolean nextSibling2()
      Moves the calling Xml object's internal reference to its next sibling. Returns true if one exists; otherwise returns false. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      the result; this method never throws ChilkatException

    • numChildrenAt

      public int numChildrenAt​(String tagPath)
      Returns the number of direct children of the element selected by tagPath. Returns -1 if the path does not identify an existing element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • numChildrenHavingTag

      public int numChildrenHavingTag​(String tag)
      Returns the number of direct children whose tag exactly equals tag. Descendants below those children are not included.
      Parameters:
      tag - the tag argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • previousSibling

      public Xml previousSibling()
      Returns an Xml object referencing the current element's previous sibling, or no object when there is no previous sibling. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • previousSibling2

      public void previousSibling2()
      Moves the calling Xml object's internal reference to its previous sibling. Returns true if one exists; otherwise returns false. Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • pruneAttribute

      public int pruneAttribute​(String attrName)
      Recursively traverses the subtree rooted at the calling element and removes every occurrence of the attribute named attrName.

      Returns the number of attributes removed.

      Parameters:
      attrName - the attrName argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • pruneTag

      public int pruneTag​(String tag)
      Recursively traverses the subtree rooted at the calling element and removes every element whose tag equals tag. Each removed element's entire descendant subtree is removed with it.

      Returns the number of matching tag occurrences removed.

      Subtree pruning: When a matching parent is removed, its descendants disappear as part of that subtree; this method is intended for structural cleanup rather than text-only removal.

      Parameters:
      tag - the tag argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • removeAllAttributes

      public void removeAllAttributes()
      Removes every attribute from the calling element. Returns true on success.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeAllChildren

      public void removeAllChildren()
      Removes all direct child elements and their subtrees from the calling element. The calling element's own tag, attributes, and text content are retained.

    • removeAttribute

      public void removeAttribute​(String name)
      Removes the attribute named name from the calling element. Returns true when the operation succeeds.
      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • removeChild

      public void removeChild​(String tagPath)
      Removes all child elements selected by tagPath beneath the calling element. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. All matches: This method removes matching children rather than returning a removed subtree. Use an ExtractChild... method when the removed element must be retained.
      Parameters:
      tagPath - the tagPath argument (not null)

    • removeChildByIndex

      public void removeChildByIndex​(int index)
      Removes the direct child at zero-based index, including that child's entire subtree.
      Parameters:
      index - the index argument

    • removeChildWithContent

      public void removeChildWithContent​(String content)
      Removes all direct children whose text content exactly equals content, including each removed child's subtree.
      Parameters:
      content - the content argument (not null)

    • removeFromTree

      public void removeFromTree()
      Detaches the calling element and its entire subtree from its parent. The detached element becomes the root of its own independent XML tree. Object remains usable: This method removes the subtree from its former document but keeps the calling Xml object referencing the detached subtree.

    • removeStyleSheet

      public int removeStyleSheet​(String attrName, String attrValue)
      Removes XML stylesheet processing instructions whose attribute named attrName has the value attrValue.

      Returns the number of matching stylesheet declarations removed, or -1 if an error occurs.

      Parameters:
      attrName - the attrName argument (not null)
      attrValue - the attrValue argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • saveBinaryContent

      public void saveBinaryContent​(String filename, boolean unzipFlag, boolean decryptFlag, String password)
      Decodes the binary content stored in this element and writes the resulting bytes to filename. Set unzipFlag and decryptFlag to reverse the transformations originally applied, and supply the corresponding password when decrypting.

      Returns true on success and false on failure.

      Parameters:
      filename - the filename argument (not null)
      unzipFlag - the unzipFlag argument
      decryptFlag - the decryptFlag argument
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • saveXml

      public void saveXml​(String fileName)
      Serializes the XML tree or subtree rooted at the current element and writes it to fileName.

      Document/output properties such as Encoding, EmitBom, EmitXmlDecl, and EmitCompact affect the generated output as applicable.

      Returns true on success and false on failure.

      Parameters:
      fileName - the fileName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • scrub

      public void scrub​(String directives)
      Recursively normalizes the XML subtree rooted at the calling element according to the comma-separated keywords in directives.

      Supported directives are:

      • AttrTrimEnds - remove leading and trailing whitespace from attribute values.
      • AttrTrimInside - replace tabs, CR, and LF with spaces and collapse repeated spaces inside attribute values.
      • ContentTrimEnds - remove leading and trailing whitespace from element content.
      • ContentTrimInside - normalize internal tabs/line breaks/spaces in element content.
      • LowercaseAttrs - convert attribute names to lowercase.
      • LowercaseTags - convert tag names to lowercase.
      • RemoveCtrl - remove US-ASCII control characters with values 0-31 except TAB, CR, and LF.

      Destructive normalization: Scrubbing modifies the tree. Use these options only when the corresponding whitespace, letter case, or control characters are not semantically significant to the application.

      Parameters:
      directives - the directives argument (not null)

    • searchAllForContent

      public Xml searchAllForContent​(Xml after, String contentPattern)
      Returns the first element whose text content matches contentPattern, regardless of tag name.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Iteration: Pass the element returned by one call as afterPtr on the next call to continue to the next match. Continue until no further element is returned.

      Parameters:
      after - the afterPtr argument (may be null)
      contentPattern - the contentPattern argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • searchAllForContent2

      public void searchAllForContent2​(Xml after, String contentPattern)
      Performs the same breadth-first content search as SearchAllForContent, but moves the calling Xml object's internal reference to the matching element instead of returning a separate element object.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Parameters:
      after - the afterPtr argument (may be null)
      contentPattern - the contentPattern argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • searchForAttribute

      public Xml searchForAttribute​(Xml after, String tag, String attr, String valuePattern)
      Returns the first element whose tag equals tag, that has an attribute named attr, and whose attribute value matches valuePattern.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Iteration: Pass the previous match as afterPtr to continue searching after that element.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      attr - the attr argument (not null)
      valuePattern - the valuePattern argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • searchForAttribute2

      public void searchForAttribute2​(Xml after, String tag, String attr, String valuePattern)
      Performs the same breadth-first tag/attribute search as SearchForAttribute, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      attr - the attr argument (not null)
      valuePattern - the valuePattern argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • searchForContent

      public Xml searchForContent​(Xml after, String tag, String contentPattern)
      Returns the first element whose tag equals tag and whose text content matches contentPattern.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Iteration: Pass the previous match as afterPtr to continue searching after that element.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      contentPattern - the contentPattern argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • searchForContent2

      public void searchForContent2​(Xml after, String tag, String contentPattern)
      Performs the same breadth-first tag/content search as SearchForContent, but moves the calling Xml object's internal reference to the matching element.

      The search is breadth-first within the subtree rooted at the caller. The afterPtr argument identifies the element after which matching should begin, allowing repeated calls to continue an iteration. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element instead.

      Wildcard patterns are case-sensitive and may contain *, where each asterisk matches zero or more characters.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      contentPattern - the contentPattern argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • searchForTag

      public Xml searchForTag​(Xml after, String tag)
      Returns the first element whose tag exactly equals tag.

      The search is breadth-first within the subtree rooted at the caller. afterPtr identifies the element after which searching begins. To begin at the first candidate, use null where the language binding permits it; ActiveX callers should pass a reference to the caller's element.

      Iteration: Pass the previous match as afterPtr to find the next matching tag. Continue until no further element is returned.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      Returns:
      a new Xml owned by the caller, or null if not found (no exception is thrown in that case); close it when done

    • searchForTag2

      public void searchForTag2​(Xml after, String tag)
      Performs the same breadth-first tag search as SearchForTag, but moves the calling Xml object's internal reference to the matching element instead of returning a separate object.

      Use afterPtr in the same way as with SearchForTag to begin or continue the search.

      Element-reference behavior: Methods that return an Xml object return another object referencing an element in the same underlying tree. Methods whose names end in 2 instead move the caller's internal reference.

      Parameters:
      after - the afterPtr argument (may be null)
      tag - the tag argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setBinaryContentBd

      public void setBinaryContentBd​(BinData data, boolean zipFlag, boolean encryptFlag, String password)
      Stores the bytes in data as binary content on this element, with optional ZIP compression and optional password-based AES encryption. The stored binary representation is emitted as Base64 text when XML is serialized.

      If zipFlag is true, the bytes are compressed first. If encryptFlag is true, the data is encrypted using Chilkat's 128-bit Rijndael/AES format and password.

      Returns true on success and false on failure.

      Round trip: Use the corresponding binary-content retrieval methods with matching decompression/decryption options to recover the original bytes.

      Parameters:
      data - the data argument (not null)
      zipFlag - the zipFlag argument
      encryptFlag - the encryptFlag argument
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setBinaryContentFromFile

      public void setBinaryContentFromFile​(String filename, boolean zipFlag, boolean encryptFlag, String password)
      Reads the bytes from filename and stores them as this element's binary content, with optional ZIP compression and optional password-based encryption. The resulting stored data is represented as Base64 when XML text is generated.

      Returns true on success and false on failure.

      Parameters:
      filename - the filename argument (not null)
      zipFlag - the zipFlag argument
      encryptFlag - the encryptFlag argument
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sortByAttribute

      public void sortByAttribute​(String attrName, boolean ascending)
      Sorts the calling element's direct children by the string value of attribute attrName. Set ascending to true for ascending order or false for descending order.

      SortCaseInsensitive controls case sensitivity for string sorting.

      Parameters:
      attrName - the attrName argument (not null)
      ascending - the ascending argument

    • sortByAttributeInt

      public void sortByAttributeInt​(String attrName, boolean ascending)
      Sorts the calling element's direct children numerically by the value of attribute attrName, interpreting each sort value as an integer rather than comparing the text lexicographically.

      Set ascending to true for ascending order or false for descending order.

      Parameters:
      attrName - the attrName argument (not null)
      ascending - the ascending argument

    • sortByContent

      public void sortByContent​(boolean ascending)
      Sorts the calling element's direct children by their text content. Set ascending to true for ascending order or false for descending order.

      SortCaseInsensitive controls case sensitivity for the string comparison.

      Parameters:
      ascending - the ascending argument

    • sortByTag

      public void sortByTag​(boolean ascending)
      Sorts the calling element's direct children by tag name. Set ascending to true for ascending order or false for descending order.

      SortCaseInsensitive controls case sensitivity for the tag-name comparison.

      Parameters:
      ascending - the ascending argument

    • sortRecordsByAttribute

      public void sortRecordsByAttribute​(String sortTag, String attrName, boolean ascending)
      Treats each direct child as a record and sorts those records by the value of attribute attrName on the record's child identified by sortTag.

      Set ascending to true for ascending order or false for descending order. String comparisons honor SortCaseInsensitive.

      Parameters:
      sortTag - the sortTag argument (not null)
      attrName - the attrName argument (not null)
      ascending - the ascending argument

    • sortRecordsByContent

      public void sortRecordsByContent​(String sortTag, boolean ascending)
      Treats each direct child as a record and sorts those records by the text content of the record's child named sortTag.

      Set ascending to true for ascending order or false for descending order. String comparisons honor SortCaseInsensitive.

      Parameters:
      sortTag - the sortTag argument (not null)
      ascending - the ascending argument

    • sortRecordsByContentInt

      public void sortRecordsByContentInt​(String sortTag, boolean ascending)
      Treats each direct child as a record and sorts those records numerically by the integer content of the record's child named sortTag.

      Numeric comparison is used instead of lexicographic string comparison. Set ascending to true for ascending order or false for descending order.

      Parameters:
      sortTag - the sortTag argument (not null)
      ascending - the ascending argument

    • swapNode

      public void swapNode​(Xml node)
      Swaps the calling element's tag, text content, and attributes with those of node.

      Returns true on success and false on failure.

      Children are not swapped: Use SwapTree when child subtrees should also be exchanged.

      Parameters:
      node - the node argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • swapTree

      public void swapTree​(Xml tree)
      Swaps the calling element's complete tree state with tree, including tag, text content, attributes, and children.

      Returns true on success and false on failure.

      Parameters:
      tree - the tree argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • tagContent

      public String tagContent​(String tagName)
      Searches the subtree rooted at the calling element for the first element whose tag equals tagName and returns that element's text content. Recursive search: Unlike direct-child getters, this search is not limited to the caller's immediate children.
      Parameters:
      tagName - the tagName argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • tagEquals

      public boolean tagEquals​(String tag)
      Returns true if the calling element's complete tag name, including any namespace prefix, exactly equals tag; otherwise returns false.
      Parameters:
      tag - the tag argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • tagIndex

      public int tagIndex​(String tagPath)
      Returns the zero-based child index of the element selected by tagPath. Returns -1 when no matching element is found at that path. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath. Index meaning: The returned index is the element's position among its parent's direct children, which is the index accepted by methods such as GetChild, RemoveChildByIndex, and the insertion methods.
      Parameters:
      tagPath - the tagPath argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • tagNsEquals

      public boolean tagNsEquals​(String ns)
      Returns true if this element's namespace-prefix portion exactly equals ns; otherwise returns false.

      For example, the namespace prefix of soapenv:Body is soapenv.

      Prefix comparison: This compares the lexical prefix, not the namespace URI bound to that prefix.

      Parameters:
      ns - the ns argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • tagUnpEquals

      public boolean tagUnpEquals​(String unprefixedTag)
      Returns true if this element's unprefixed tag exactly equals unprefixedTag; otherwise returns false.

      For example, the unprefixed tag of soapenv:Body is Body.

      Parameters:
      unprefixedTag - the unprefixedTag argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • unzipContent

      public void unzipContent()
      Reverses ZipContent: decodes and decompresses the calling element's compressed content and replaces the stored Base64-compressed representation with the original content.

      Returns true on success and false on failure.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unzipTree

      public void unzipTree()
      Reverses ZipTree: decompresses the stored representation and reconstructs the calling element's previously compressed subtree.

      The element's tag and attributes, which are not replaced by ZipTree, remain associated with the restored tree.

      Returns true on success and false on failure.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateAt

      public void updateAt​(String tagPath, boolean autoCreate, String value)
      Sets the text content of the element selected by tagPath to value.

      If autoCreate is true, missing elements along the path are created as needed. If it is false, the update requires the target path to already exist.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Parameters:
      tagPath - the tagPath argument (not null)
      autoCreate - the autoCreate argument
      value - the value argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateAttrAt

      public void updateAttrAt​(String tagPath, boolean autoCreate, String attrName, String attrValue)
      Sets attribute attrName to attrValue on the element selected by tagPath. The attribute is added when it does not already exist.

      If autoCreate is true, missing elements along the path are created as needed. If it is false, the target path must already exist.

      Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.

      Parameters:
      tagPath - the tagPath argument (not null)
      autoCreate - the autoCreate argument
      attrName - the attrName argument (not null)
      attrValue - the attrValue argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateAttribute

      public void updateAttribute​(String attrName, String attrValue)
      Sets attribute attrName to attrValue. If the attribute already exists its value is replaced; otherwise the attribute is added.

      Returns true on success and false on failure.

      Parameters:
      attrName - the attrName argument (not null)
      attrValue - the attrValue argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateAttributeInt

      public void updateAttributeInt​(String attrName, int value)
      Sets attribute attrName to the decimal representation of integer value. Use UpdateAttribute for string values.

      Returns true on success and false on failure.

      Parameters:
      attrName - the attrName argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • updateChildContent

      public void updateChildContent​(String tagPath, String value)
      Sets the text content of the child selected by tagPath to value. Missing elements along the path are automatically created as needed. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      value - the value argument (not null)

    • updateChildContentInt

      public void updateChildContentInt​(String tagPath, int value)
      Sets the content of the child selected by tagPath to the decimal representation of integer value. Tag paths: A tag path is Chilkat's |-separated child-navigation syntax, for example tagA|tagB|tagC. It is not XPath.
      Parameters:
      tagPath - the tagPath argument (not null)
      value - the value argument

    • zipContent

      public void zipContent()
      ZIP-compresses this element's text content and replaces the original content with Base64-encoded compressed data.

      Returns true on success and false on failure.

      Reversible transformation: Call UnzipContent to restore the original content.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • zipTree

      public void zipTree()
      ZIP-compresses the calling element's content together with its entire child subtree and replaces that structure with Base64-encoded compressed data.

      The calling element's tag and attributes are not changed. Call UnzipTree to reconstruct the compressed subtree.

      Returns true on success and false on failure.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why