Archives for 2010

The Announcement

The first public release of the new Simple Java API for ODF is now available for download. This API radically simplifies common document automation tasks, allowing you to perform tasks in a few lines of code that would require hundreds if you were manipulating the ODF XML directly.

The Simple API is part of the ODF Toolkit Union open source community and is available under the Apache 2.0 license.   JavaDoc, demonstration code and a “Cookbook” are also available on the project’s website.

The Background

I first proposed an ODF Toolkit back in 2006, shortly after I got involved with ODF.  It was clear then that one of the big advantages of ODF, compared to proprietary binary formats, is that ODF lent itself to manipulation using common, high level tools. I made a list of the top 2o document-based “patterns of use“, but the key ones are in the following areas:

• Mail merge style field replacement
• Combining documents fragments/document assembly
• Data-drive document generation
• Information extraction

The hope was that we could it easy to write such applications using ODF.

So why wouldn’t this be easy?   In the end ODF is just ZIP and XML and every programming platform knows how to deal with these formats, right?

Yes, this is true.  However there clearly are a lot of details to worry about.  Although ZIP and XML are relatively simple technologies, defining exactly how ODF works requires over a thousand pages.  This level of detail is necessary if you are writing a word processor or a spreadsheet.  But you really don’t need to know ODF at this level in order to accomplish typical document automation tasks.

There have been several other attempts at writing toolkits in this space.  Some, such as the ODF Toolkit Union’s ODFDOM project have aimed for a low-level, Java API, with a 1-to-1 correspondence with ODF’s elements and attributes.  Others, like lpOD’s Python API have taken a higher-level view of ODF.  You can make a good argument for either approach.  Each has its advantages and disadvantages.

The advantage of the low-level API is that if want to manipulate an existing ODF document, which in general can contain any legal ODF markup, then you need an API that understands 100% of ODF.  But in order to understand that API would require understanding the entire ODF standard.  So that is too complicated for most application developers.

If you write a high level API, then it may be easy to use, but how can you then guarantee that it can losslessly manipulate an arbitrary ODF document?

I think the best approach might be a blended approach.  Build a low-level API that does 100% of ODF, and then on top of that have a layer that provides higher-level functions that do the most-common tasks.  This gives you the benefits of completeness and simplicity.  This is the approach we have taken with the Simple Java API for ODF.   It is built upon the schema-driven ODFDOM API, to give it a solid low-level foundation.  And on top of that it adds high-level functions.  How high?  The aim is provide operations that are similar to what you as an end-user would have available in the UI, or what you as an application developer would have with VBA or UNO macros.  So adding high level content, like tables or images.  Search and replace operations.  Cut and paste.   Simple, but still powerful.

A Quick Example

As a quick illustration of the level of abstraction provided by the Simple Java API for ODF, let’s do some simple app.  We want to load ODF documents, search for stock ticker symbols and add a hyperlink for each one to the company’s home page.

So, start with a document that looks like this:

We want to take that and find each instance of “FOO” and add a hyperlink to “http://www.foo.com” and so on.  If you tried this operation with an ODF document directly, it could certainly be done.  But it would require a good deal of familiarity with the ODF standard.  But using the Simple API you can do this without touching XML directly.

Let’s see how this is done.

// basic Java core libraries that any Java developer knows about
import java.net.URL;
import java.io.File;

// Simple API classes for text documents, selections and text navigation
import org.odftoolkit.simple.TextDocument;
import org.odftoolkit.simple.text.search.TextSelection;
import org.odftoolkit.simple.text.search.TextNavigation;

public class Linkify
{
    public static void main(String[] args)
    {
        try
        {
            // load text document (ODT) from disk.
            // could also load from URL or stream
            TextDocument document=(TextDocument)TextDocument.loadDocument("foobar.odt");

            // initialize a search for "Foo".
            // we'll be adding regular expression support as well
            TextNavigation search = new TextNavigation("FOO", document);

            // iterate through the search results
            while (search.hasNext())
            {
                // for each match, add a hyperlink to it
                TextSelection item = (TextSelection) search.getCurrentItem();
                item.addHref(new URL("http://www.foo.com"));
            }

            // save the modified document back to a new file
            document.save(new File("foobar_out.odt"));
        }

        catch (Exception e)
        {
            e.printStackTrace();
        }
    }

}

Run the code and you get a new document, with the hyperlinks added, like this:
Simple enough? I think so.

How to get involved

We really want your help with this API.  This is not one of those faux-open source projects, where all the code is developed by one company.  We want to have a real community around this project.  So if you are at all interested in ODF and Java, I invite you to take a look:

1. Download the 0.2 release of the Simple Java API for ODF.  The wiki also has important info on install pre-reqs.
2. Work through some of the cookbook to get an idea on how the API works.
3. Sign up and join the ODF Toolkit Union project.
4. Join the users mailing list and ask questions.  Defect reports can go to our Bugzilla tracker.
5. If you want to contribute patches, more info on the wiki for how to access our repository.

I think you will enjoy this graphic. Click for a larger view.  This is a chart of all of the standards that ODF 1.2 refers to, what we standards geeks call “normative references”.  A normative reference takes definitions and requirements from one standard and uses it, by reference, in another.  It is a form of reuse, reusing the domain analysis, specification and review work that went into creating the other standard.  Each reference is color coded and grouped by the organization that owns the referenced standard, W3C, IETF, ISO, etc., and placed on a time line according to when that standard was published

I’m sure each reader will note interesting patterns on their own, but a few things stood out in my mind when looking at this chart:

• ODF is very much built on top of web and internet standards from the W3C and IETF.  That is where the bulk of our references are from.  This is true not only of the older stuff from the web’s initial standardization effort in 1998-2000, but also for more recent work like GRDDL, RDFa and XForms 1.1.  As documents start living more of a dual-life, on the desktop and on the web (and even mobile), this web standards heritage of ODF will continue to open new doors for ODF implementors and users.
• Except for a few bedrock standards like Unicode, ISO just doesn’t register.  They simply are not doing a lot of relevant work in this area.
• A good response when you are faced with critics who claim that ODF is just based on what OpenOffice.org does.  You can point out that OpenOffice was first released as open source in  2000 and via StarOffice had a proprietary history going back to 1984.  So if ODF is merely a dump of what OpenOffice does, then why is ODF built on so many standards that did not exist in 2000?  Does time travel explain it?  Or maybe clairvoyance?  Or maybe, just maybe it is just good engineering to reference relevant standards in your domain rather than reinvent a proprietary version of everything?