guide.xml from PeerWriter at Krugle

Show guide.xml syntax highlighted

<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://www.dom4j.org/guide.xml">

  <properties>
    <title>Quick Start Guide</title>
    <author email="jstrachan@apache.org">James Strachan</author>
 </properties>
 
  <body>
    
    <p>The Quick Start Guide will hopefully show you how to do the basic operations in dom4j.
    </p>

    <section name="Parsing XML">
      <p>One of the first things you'll probably want to do is to parse an 
        XML document of some kind. This is easy to do in <i>dom4j</i>.
        The following code demonstrates how to this.
      </p>
<pre>
import java.net.URL;

import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.io.SAXReader;

public class Foo {

    public Document parse(URL url) throws DocumentException {
        SAXReader reader = new SAXReader();
        Document document = reader.read(url);
        return document;
    }
}
</pre>
    </section>

    <section name="Using Iterators">
      <p>A document can be navigated using a variety of methods that return
        standard Java Iterators. For example
      </p>
<pre>
    public void bar(Document document) throws DocumentException {

        Element root = document.getRootElement();

        // iterate through child elements of root
        for ( Iterator i = root.elementIterator(); i.hasNext(); ) {
            Element element = (Element) i.next();
            // do something
        }

        // iterate through child elements of root with element name "foo"
        for ( Iterator i = root.elementIterator( "foo" ); i.hasNext(); ) {
            Element foo = (Element) i.next();
            // do something
        }

        // iterate through attributes of root 
        for ( Iterator i = root.attributeIterator(); i.hasNext(); ) {
            Attribute attribute = (Attribute) i.next();
            // do something
        }
     }
</pre>
    </section>

    <section name="Powerful Navigation with XPath">
      <p>In <i>dom4j</i> XPath expressions can be evaluated on the Document 
        or on any Node in the tree (such as Attribute, Element or 
        ProcessingInstruction).
        This allows complex navigation throughout the document with a single 
        line of code. For example.
      </p>
<pre>
    public void bar(Document document) {
        List list = document.selectNodes( "//foo/bar" );

        Node node = document.selectSingleNode( "//foo/bar/author" );

        String name = node.valueOf( "@name" );
    }
</pre>
      <p>For example if you wish to find all the hypertext links in an XHTML document
        the following code would do the trick.
      </p>
<pre>
    public void findLinks(Document document) throws DocumentException {

        List list = document.selectNodes( "//a/@href" );

        for (Iterator iter = list.iterator(); iter.hasNext(); ) {
            Attribute attribute = (Attribute) iter.next();
            String url = attribute.getValue();
        }
    }
</pre>
      <p>If you need any help learning the XPath language we highly recommend
        the <a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html">Zvon tutorial</a> 
        which allows you to learn by example.
      </p>
    </section>


    <section name="Fast Looping">
      <p>If you ever have to walk a large XML document tree
        then for performance we recommend you use the fast 
        looping method which avoids the cost of creating
        an Iterator object for each loop. For example
      </p>
<pre>
    public void treeWalk(Document document) {
        treeWalk( document.getRootElement() );
    }

    public void treeWalk(Element element) {
        for ( int i = 0, size = element.nodeCount(); i &lt; size; i++ ) {
            Node node = element.node(i);
            if ( node instanceof Element ) {
                treeWalk( (Element) node );
            }
            else {
                // do something....
            }
        }
    }
</pre>
    </section>


    <section name="Creating a new XML document">
      <p>Often in <i>dom4j</i> you will need to create a new document
        from scratch. Here's an example of doing that.
      </p>
<pre>
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;

public class Foo {

    public Document createDocument() {
        Document document = DocumentHelper.createDocument();
        Element root = document.addElement( "root" );

        Element author1 = root.addElement( "author" )
            .addAttribute( "name", "James" )
            .addAttribute( "location", "UK" )
            .addText( "James Strachan" );
        
        Element author2 = root.addElement( "author" )
            .addAttribute( "name", "Bob" )
            .addAttribute( "location", "US" )
            .addText( "Bob McWhirter" );

        return document;
    }
}
</pre>
    </section>

    <section name="Writing a document to a file">
      <p>A quick and easy way to write a Document (or any Node) to a Writer
       is via the write() method.
      </p>
<pre>
  FileWriter out = new FileWriter( "foo.xml" );
  document.write( out );
</pre>

      <p>If you want to be able to change the format of the output, such as pretty
        printing or a compact format, or you want to be able to work with
        Writer objects or OutputStream objects as the destination, then you can use the XMLWriter class.
      </p>
<pre>
import org.dom4j.Document;
import org.dom4j.io.OutputFormat;
import org.dom4j.io.XMLWriter;

public class Foo {

    public void write(Document document) throws IOException {

        // lets write to a file
        XMLWriter writer = new XMLWriter(
            new FileWriter( "output.xml" )
        );
        writer.write( document );
        writer.close();


        // Pretty print the document to System.out
        OutputFormat format = OutputFormat.createPrettyPrint();
        writer = new XMLWriter( System.out, format );
        writer.write( document );

        // Compact format to System.out
        format = OutputFormat.createCompactFormat();
        writer = new XMLWriter( System.out, format );
        writer.write( document );
    }
}
</pre>
    </section>

    <section name="Converting to and from Strings">
      <p>If you have a reference to a Document or any other Node such as an 
        Attribute or Element, you can turn it into the default XML text
        via the asXML() method.
      </p>
<pre>
        Document document = ...;
        String text = document.asXML();
</pre>
      <p>If you have some XML as a String you can parse it
        back into a Document again using the helper method 
        DocumentHelper.parseText()
      </p>
<pre>
        String text = "&lt;person&gt; &lt;name&gt;James&lt;/name&gt; &lt;/person&gt;";
        Document document = DocumentHelper.parseText(text);
</pre>
    </section>


    <section name="Styling a Document with XSLT">
      <p>Applying XSLT on a Document is quite straightforward using the 
        <a href="http://java.sun.com/xml/">JAXP</a> API from Sun. 
        This allows you to work against any XSLT engine such as Xalan or SAXON.
        Here is an example of using JAXP to create a transformer and then 
        applying it to a Document.
      </p>
<pre>
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;

import org.dom4j.Document;
import org.dom4j.io.DocumentResult;
import org.dom4j.io.DocumentSource;

public class Foo {

    public Document styleDocument(
        Document document, 
        String stylesheet
    ) throws Exception {

        // load the transformer using JAXP
        TransformerFactory factory = TransformerFactory.newInstance();
        Transformer transformer = factory.newTransformer( 
            new StreamSource( stylesheet ) 
        );

        // now lets style the given document
        DocumentSource source = new DocumentSource( document );
        DocumentResult result = new DocumentResult();
        transformer.transform( source, result );

        // return the transformed document
        Document transformedDoc = result.getDocument();
        return transformedDoc;
    }
}
</pre>

    </section>
  </body>
</document>
See more files for this project here