on java and xml

but not on test environments vs theory; did you know that eclipse workspaces are really useful for managing projects?
keywords: java, xml, api, dom, reading, writing, modifying, node, nodelist, element, stream, transform

"Unfortunately DOM XML documents in Java have a reputation for being hard to create. This simply isn't true. The construction process is very wordy though, but if you have a cheat sheet (like this tutorial), then they really aren't so bad."
t. gene davis

i have been trial-and-erroring for a while because trying to understand what those misanthropes responsible for the java/xml/dom documentation were getting at is like trying to understand what a new sexual partner is thinking.

the stuff that turned out to be easy to implement had only embittered me the more - the explanations don't need to be so complicated. i smell job justification and snobbery.

---
note: all imports must be from org.w3c.dom.
making that mistake can be embarrassing.

1. document building
DocumentBuilderFactories make sense, as do DocumentBuilders.

DocumentBuilders parse an input stream (or file) to create a Document; now we have the basic data accessible by code.

2. what's in a Node?
it's incredibly useful to cast from a Node to an Element. that'll give you access to node attributes without any silly runarounds.

so a Node can return a NodeList, and a NodeList can be manipulated with the following (useful) commands:

• NodeList.item(0): the root element of the current NodeList as a Node.
• if (Node.getNodeType() == Node.ELEMENT_NODE)
  Element = (Element)Node;
• Node.getNodeName(): returns the tag name of the node, or begins with '#' to indicate a special node type (see the table)
• Element.getTagName(): returns the name of the tag
• Element.getTextContent(): it's apparently not cool to have both tags and text content in an XML node. try to avoid doing this, because otherwise you won't have any (reasonable, simple) way to extract *just* the text.
  in other words, if you're going to pull actual text from a node, make sure it's a leaf node. otherwise, use attributes.
• Node.getAttributes().item(index): retrieves the indexed attribute, eg.
  Node.getAttributes().item(0)
  for
  <myTag id="4" />
• if you want to, say, increment an Element's "id" attribute:
  try{
    if (el.getAttribute("id").length() > 0){
      el.setAttribute("id",
        String.valueOf(
          Integer.parseInt(
            el.getAttribute("id")
          ) + 1
        )
      );
    } else el.setAttribute("id", "1");
  } catch (Exception e) {
    // catch clause
  }

3. transforming
"transforming" means writing the xml to a stream. the TransformerFactory's Transformer must be passed a Document. there is no difference between a Document and a Node that contains child nodes; the parameter for the DOMSource is interchangeable.

but not a NodeList. if you have one of those, you must use its item(0) to get at the Node.

---
there - that doesn't sound so bad, does it? so why the hell is it so difficult to find someone who can explain it without assuming that i like having my brain fried?

NOTE: yeah, i know this isn't complete. i'm only to happy to have you submit questions / criticism.