In Example 3.10, “Extracting Headings from an OpenDocument File”, we extracted the headings from an OpenOffice.org document and placed them into a new document. In this case study, we will add the headings to the current document. They will be represented as a bulleted list in a section at the beginning of the document. This is definitely the most ambitious example so far. In fact, at several points we almost abandoned the idea in favor of a simpler example. However, we realized that we would have to handle the tricky details at some point, and there was no time like the present.

This program is written in Java and is run from the command line. It takes two arguments: the name of the original file, and the name of the new file. We had considered simply modifying the original file in place, but if you ran the program twice you’d end up with two sets of bullet items. Here’s the plan:

We start with the declarations of imported classes, which is not terribly illuminating, so we won’t duplicate it here. You can see them in the AddOutline.java file in the ch03 directory in the downloadable example files.

We continue with the class declaration and class variables. In addition to finding the last list, paragraph, and section style numbers, we also need to keep track of their location in the document tree so that we can add our new styles immediately after the existing ones.

public class AddOutline
{
    /* The parsed document */
    protected Document document = null;
    
    /* Permanent pointer to root element of output document */
    protected Element documentRoot;

    /* List of heading elements */
    protected NodeList headingElements;

    /* Last numbers for paragraph, list, and section styles */
    int         lastParaNumber = 0;
    int         lastListNumber = 0;
    int         lastSectionNumber = 0;

    /* Node locations of last paragraph, list, and section styles */
    Node        lastParaNode = null;
    Node        lastListNode = null;
    Node        lastSectionNode = null;

    /* File descriptors */
    File        inFile;
    File        outFile;
    
    /* Streams for reading and writing jar files */
    JarInputStream  inJar;
    JarOutputStream outJar; 	

The main program is simplicity itself; it checks for the proper number of arguments, creates a class, and hands the arguments to the modifyDocument method.

public static void main(String argv[]) {

    // check for proper number of arguments
    if (argv.length != 2) {
        System.err.println("usage: java AddOutline filename newfilename");
        System.exit(1);
    }

    AddOutline adder = null;

    adder = new AddOutline();
    adder.modifyDocument(argv);  

} // main(String[])

Here is the modifyDocument method

protected void modifyDocument(String argv[])
{
    JarEntry inEntry;
    JarEntry outEntry;

    /* Create file descriptors */
    inFile = new File(argv[0]); 
    outFile = new File(argv[1]);

    openInputFile();

    /* Get the manifest from the input file */
    Manifest manifest = inJar.getManifest( );

    /* Open output file, copying manifest if it existed */
    try
    {
        if (manifest == null)
        {
            outJar = new JarOutputStream(new FileOutputStream(outFile));
        }
        else
        {
            outJar = new JarOutputStream(new FileOutputStream(outFile),
                manifest);
        }
    }
    catch (IOException e)
    {
        System.err.println("Unable to open output file.");
        System.exit(1);
    }

    try 
    {
        byte    buffer[] = new byte[16384];
        int     nRead;

        while ((inEntry = inJar.getNextJarEntry()) != null)
        {
            if (!inEntry.getName().equals("content.xml"))
            {
                /*
                 * Create output entry based on information in
                 * corresponding input entry
                 */
                outEntry = new JarEntry(inEntry);
                outJar.putNextEntry(outEntry);
                
                /* Copy data */
                while ((nRead = inJar.read(buffer, 0, 16384)) != -1)
                {
                    outJar.write(buffer, 0, nRead);
                }
            }
        }

        inJar.close(); 
        openInputFile();

        while ((inEntry = inJar.getNextJarEntry()) != null &&
            !(inEntry.getName().equals("content.xml")))
        {
            /* do nothing */
        }

        /*
         * Create output entry based on information in
         * corresponding input entry, but update its
         * timestamp.
         */
        outEntry = new JarEntry(inEntry);
        outEntry.setTime(new Date().getTime());
        outJar.putNextEntry(outEntry);

        
        document = readContent();   /* parse content.xml */
        processContent();   /* add styles and bulleted list */
        writeContent();     /* write it to output JAR file */

        outJar.close();
    }
    catch (IOException e)
    {
        System.err.println("Error while creating new file");
        e.printStackTrace();
    }
}

	Start by opening the input file, and copying its manifest file (if any) to the output file. We use a method to open the input file, because we’ll need to do it twice.
	The next stage is to copy all the JAR entries other than the content.xml file. The try block that starts here extends to nearly the end of the method; any error gives a generic error message and a stack trace.
	We must then close the input file and re-open it in order to find the content.xml JAR entry and process it. You may be wondering why we didn’t just do this as one loop, copying all the entries except content.xml and processing it specially. We tried that, and it doesn’t work; the XML parser closes its input file when it finishes, so the loop would fail with an "Input stream closed" error when it got to the entry after content.xml In this second loop, we use a while loop with no statements in the loop body to get to the desired entry in the JAR file.
	Here’s where the main work of creating the outline occurs; we will look at it in detail shortly.

Here’s the code that opens the input file; nothing special to see here—keep moving along.

public void openInputFile()
{
    try
    {
        inJar = new JarInputStream(new FileInputStream(inFile));
    }
    catch (IOException e)
    {
        System.err.println("Unable to open input file.");
        System.exit(1);
    }
}

It doesn’t take much code to parse the XML file either. We need to create a parser, set its input source to the entry from the JAR file, and get the result when everything finishes. We must also have Xerces ignore any DTDs it might find in the <!DOCTYPE>; the relevant line is shown in boldface, and uses the ResolveDTD class described in the section called “Getting Rid of the DTD”.

public Document readContent( )
{
    try
    {
        DOMParser parser = new org.apache.xerces.parsers.DOMParser();
        parser.setEntityResolver(new ResolveDTD());
        parser.parse(new InputSource(inJar));
        return parser.getDocument();
    }
    catch (Exception e)
    {
        e.printStackTrace(System.err);
        return null;
    }
}

Now we must add the styles and text to the document tree; this is done in method processContent. The lines shown in boldface are methods that do much of the heavy lifting; we will look at each of those methods individually.

public void processContent()
{
    Node        autoStyles;
    Element     officeBodyStart;    /* the <office:body> element */
    Element     officeTextStart;    /* the <office:text> element */
    Element     textStart;          /* place to insert new text */
    Element     element;
    
    if (document == null)
    {
        return;
    }
    
    documentRoot = (Element) document.getDocumentElement();

    headingElements = document.getElementsByTagName("text:h"); 
    if (headingElements.getLength() == 0)
    {
        return;
    }
    
    autoStyles = findFirstChild(documentRoot, "office:automatic-styles"); 
    findLastItems(autoStyles);

    /*
     * Prepare to add the new styles by going to the next
     * available number. We'll insert the new style before
     * the next sibling of the last node. We have to do this
     * crazy thing because there is no "insertAfter" method.   
     */
    lastParaNumber++;
    lastListNumber++;
    lastSectionNumber++;
    if (lastParaNode != null)
    {
        lastParaNode = lastParaNode.getNextSibling();
    }
    if (lastListNode != null)
    {
        lastListNode = lastListNode.getNextSibling();
    }
    if (lastSectionNode != null)
    {
        lastSectionNode = lastSectionNode.getNextSibling();
    }
    
    /*
     * Create a <style:style> element for the new paragraph,
     * set its attributes and insert it after the last paragraph
     * style.
     */
    element = document.createElement("style:style");
    element.setAttribute("style:name", "P" + lastParaNumber);
    element.setAttribute("style:family", "paragraph");
    element.setAttribute("style:list-style-name", "L" + lastListNumber);
    element.setAttribute("style:parent-style-name", "Standard");        
    autoStyles.insertBefore(element, lastParaNode);

    /*
     * Create a <style:style> element for the new section,
     * set its attributes and insert it after the last section
     * style.
     */
    element = document.createElement("style:style");
    element.setAttribute("style:name", "Sect" + lastSectionNumber);
    element.setAttribute("style:family", "section");
    addSectionProperties(element);
    autoStyles.insertBefore(element, lastSectionNode);

    /*
     * Create a <text:list-style> element for the new list,
     * set its attributes and insert it after the last list
     * style.
     */
    element = document.createElement("text:list-style");
    element.setAttribute("style:name", "L" + lastParaNumber);
    addBullets(element);
    
    autoStyles.insertBefore(element, lastListNode);
    
    /*
     * Now proceed to where we will add text;
     * it's just after the first <text:sequence-decls>
     * in the <office:text> in the <office:body> 
     */
    officeBodyStart = findFirstChild(documentRoot, "office:body");
    officeTextStart = findFirstChild(officeBodyStart, "office:text");
    textStart = findFirstChild(officeTextStart, "text:sequence-decls");
    textStart = getNextElementSibling( textStart ); 
    
    /*
     * Add a section
     */
    element = document.createElement("text:section");
    element.setAttribute("text:style-name", "Sect" + lastSectionNumber);
    element.setAttribute("text:name", "Section" + lastSectionNumber);
    addHeadings(element);
    officeTextStart.insertBefore(element, textStart);
}

	Gather up all the <text:h> elements in the document; if there are none, then our job here is done.
	This line uses a utility method (findFirstChild) to find the first child of the document root whose element name is office:automatic-styles.
	Expanding on the comment: we want to place the new paragraph style after the last paragraph style in the current document, the new section style after the last existing style, etc. However, there’s no insertAfter method, so we have to insertBefore the next sibling of the desired node.
	We haven’t discussed the <text:sequence-decls> element yet; it’s used for numbering items in OpenOffice.org documents. The main text in your document normally immediately follows this element. However, if you have any text nodes (such as newlines) between elements, the DOM getNextSibling will not give us what we want; thus, we use our own utility method getNextElementSibling.

As long as we’re talking about the utility routines, they’re fairly short, so we may as well present them here:

/*
 * Find first element with a given tag name
 * among the children of the given node.
 */
public Element findFirstChild(Node startNode, String tagName)
{
    startNode = startNode.getFirstChild();
    while (! (startNode != null &&
        startNode.getNodeType() == Node.ELEMENT_NODE &&
        ((Element)startNode).getTagName().equals(tagName)))
    {
        startNode = startNode.getNextSibling();
    }
    return (Element) startNode;
}

/*
 *  Find next sibling that is an element
 */
public Element getNextElementSibling( Node node )
{
    node = node.getNextSibling();
    while (node != null &&
        node.getNodeType() != Node.ELEMENT_NODE)
    {
        node = node.getNextSibling();
    }
    return (Element) node;
}

The next method, addSectionProperties is more of a convenience method than anything else:

/*
 * Add the appropriate properties to make a single-column
 * section
 */
public void addSectionProperties(Element sectionStyle)
{
    Element properties;
    Element columns;

    properties = document.createElement("style:section-properties");
    properties.setAttribute("text:dont-balance-text-columns",
        "false");

    columns = document.createElement("style:columns");
    columns.setAttribute("fo:column-count", "0");
    columns.setAttribute("fo:column-gap", "0cm");

    properties.appendChild(columns);
    sectionStyle.appendChild(properties);
}

The addBullets method is also quite straightforward; it’s a simple loop to create the ten levels of bullet styles. All levels except the first have text:space-before. Ordinarily OpenOffice.org creates its bullet styles with the StarSymbol font, and references a style named Bullet Symbols in the styles.xml file. We are dispensing with that, so our new document will use the bullet symbol from the default font.

/*
 * Add the ten bullet styles to the <text:list-style> element. 
 */
public void addBullets(Element listLevelStyle)
{
    int     level;
    Element bullet;
    Element properties;
    for (level = 1; level <= 10; level++)
    {
        bullet = document.createElement("text:list-level-style-bullet");
        bullet.setAttribute("text:level", Integer.toString(level));
        bullet.setAttribute("text:bullet-char", "\u2022");

        properties = document.createElement("style:list-level-properties");
        if (level != 1)
        {
            properties.setAttribute("text:space-before",
                Double.toString((level-1) * 0.5) + "cm");
        }
        properties.setAttribute("text:min-label-width", "0.5cm");
        bullet.appendChild(properties);
        listLevelStyle.appendChild(bullet);
    }
}

Adding the headings is conceptually a recursive process, since each new level of heading opens a nested list. However, there is no guarantee that heading levels will increase and decrease sequentially; a level three heading can be followed by a level seven heading, followed by a level one heading. (This is not good document design, but it is certainly possible.) Thus, rather than write this method recursively, we decided to use an array to simulate a stack. Here’s the pseudo-code:

/* Add headings to a section */
public void addHeadings(Element startElement)
{
    int currentLevel = 0;
    int headingLevel;
    int i;
    int level;
    Element ulist[] = new Element[10];
    Element listItem;
    Element paragraph;
    Text    textNode;

    for (i=0; i < headingElements.getLength(); i++)
    {
        headingLevel = Integer.parseInt(
            ((Element)headingElements.item(i)).getAttribute("text:level"));
        if (headingLevel > currentLevel)
        {
            for (level = currentLevel; level < headingLevel; level++)
            {
                ulist[level] = document.createElement(  
                    "text:list");
                if (level == 0)
                {
                    ulist[level].setAttribute("text:style-name",
                        "L" + lastListNumber);
                }
            }
            currentLevel = headingLevel;
        }
        else if (headingLevel < currentLevel)
        {
            closeLists(ulist, currentLevel, headingLevel); 
            currentLevel = headingLevel;
        }

        /* Now append this heading as an item to current level */

        listItem = document.createElement("text:list-item");  
        paragraph = document.createElement("text:p");
        paragraph.setAttribute( "text:style-name", "P" + lastParaNumber );
        textNode = document.createTextNode("");
        textNode = accumulateText(
            (Element) headingElements.item(i),
            textNode);
        paragraph.appendChild(textNode);
        listItem.appendChild(paragraph);
        ulist[currentLevel-1].appendChild(listItem);

    }
    if (currentLevel != 1) 
    {
        closeLists(ulist, currentLevel, 1);
    }
    startElement.appendChild(ulist[0]);
}   

	We add levels by creating <text:list> elements. Only the first level unordered list has a text:style-name attribute.
	The work of closing lists when the level decreases has been passed on to a separate routine.
	No matter whether we have added levels, closed levels, or are at the same level, we have to add a <text:list-item> at the current level. The accumulateText method gathers all the text nodes in the heading.
	Another call to the closeLists method closes any nested lists.

Here is the closeLists method. Each <text:list> that is being closed is within a <text:list-item> element of its parent list.

/*
 * Join elements in the ulist[] array to close all open lists
 * from currentLevel back down to newLevel
 */
public void closeLists(Element ulist[], int currentLevel, int newLevel)
{
    int i;
    Element listItem;
    for (i = currentLevel-1; i > newLevel-1; i--)
    {
        listItem = document.createElement("text:list-item");
        listItem.appendChild(ulist[i]);
        ulist[i-1].appendChild(listItem);
    }
}

Finally, the accumulateText method, which recursively visits all the child nodes of the <text:h> element in question. Tabs and line breaks are replaced with a single blank each; any other elements are ignored.

/*
 * Return a Text node that contains all the accumulated text
 * from the child nodes of the given element.
 */
public Text accumulateText(Element element, Text text)
{
    Node node = element.getFirstChild();
    while (node != null)
    {
        if (node.getNodeType() == Node.TEXT_NODE)
        {
            text.appendData(((Text) node).getData());
        }
        else if (node.getNodeType() == Node.ELEMENT_NODE)
        {
            if (((Element) node).getTagName().equals("text:tab-stop") ||
                ((Element) node).getTagName().equals("text:line-break"))
            {
                text.appendData(" ");
            }
            else
            {
                text = accumulateText((Element) node, text);
            }
        }
        node = node.getNextSibling();
    }
    return text;
}

This covers all the methods used to process the document tree. All that remains is the method to serialize the document tree, writing it to the new document’s content.xml JAR file entry.

public void writeContent()
{
    if (document == null)
    {
        return;
    }
    PrintWriter out = null;
    try
    {
        out =
        new PrintWriter(new OutputStreamWriter(outJar, "UTF-8"));  
    }
    catch (Exception e)
    {
        System.out.println("Error creating output stream");
        System.out.println(e.getMessage());
        System.exit(1);
    }
    OutputFormat oFormat = new OutputFormat("xml", "UTF-8", false); 
    XMLSerializer serial = new XMLSerializer(out, oFormat); 
    try
    {
        serial.serialize(document);
    }
    catch (java.io.IOException e)
    {
        System.out.println(e.getMessage());
    }
}

	First, construct an output stream with your favorite encoding method
	A serializer requires an output format. This constructor’s three parameters are the output method (which is normally one of "xml", "html", or "text"); the character encoding, which should be "UTF-8" to keep your international clients happy; and a boolean that tells whether the output should be indented or not. Set this to false to avoid unwanted whitespace text nodes.
	The OutputFormat is used when creating the serializer.