Contents


OpenDocument API - ODFDOM

ODFDOM is an OpenDocument (ODF) framework. It's purpose is to provide an easy common way to create, access and manipulate ODF files, without requiring detailed knowledge of the ODF specification. It is designed to provide the ODF developer community an easy lightwork programming API, portable to any object-oriented language.

Overview

The ODFDOM project's objective is to provide an easy API for reading, writing and manipulating documents of the OpenDocument format (ODF). To archive this, the ODFDOM API follows a layered approach to access documents. A layered design is the robust foundation for a well-designed structure like modularity.

Overview over ODFDOM layers:


ODFDOM is part of the ODF Toolkit project. Development is discussed on the dev mailing list and in the ODFDOM forum.


The ODFDOM Layers

The ODF Package / Physical Layer

At this level a document is represented by a bundle of named resources zipped to a package.

For instance, an ODF text document like 'myVacation.odt' might contain the following files:

Note: All file streams aside of the '/Pictures' directory and its content are specified by the ODF standard. Furthermore, the file streams are similar for all types of ODF documents.

The main requirements for this layer are:

All sources of the Package/Physical layer are organized in ODFDOM beyond org.openoffice.odf.pkg.*

The following example illustrates how to add a graphic to the package level (although not shown by an ODF application (like OpenOffice.org), as not used by the shown content): 

import org.openoffice.odf.pkg.OdfPackage;
[...]

// loads the ODF document package from the path
OdfPackage pkg = OdfPackage.loadPackage("/home/myDocuments/myVacation.odt");

// loads the image from the URL and inserts the image in the package, adapting the manifest
pkg.insert(new URI("/myweb.org/images/myHoliday.png"), "/Pictures/myHoliday.png");
pkg.save("/home/myDocuments/myVacation.odt");


The ODF Typed DOM / XML Layer

At this level, all XML file streams of the document are accessible via the W3C DOM API, but only the ODF standardized XML file streams of the document (e.g. content.xml, meta.xml) have their own classes representing their ODF XML elements. Foreign XML within a specified ODF XML file will remain in the document model in general and won't be neglected unless desired ( which still might be a future option).

Example of the ODF XML representing a table in ODF:

Note: In the OpenDocument standard the ODF elements are reused among all document types. The above XML of a table is for instance equally usable in Text and Spreadsheet documents.

This XML would be mapped to a W3C derived ODF DOM class structure:

All sources of the typed DOM/XML layer are organized beyond org.openoffice.odf.dom.*

The sources for the ODF elements are all generated from the ODF grammar (RelaxNG schema) using the following naming conventions in the Java reference implementation:

Note: The element local names 'h' and 'p' have been renamed to the classes 'Heading' and 'Paragraph' for usability reasons.

The following example illustrates how to add a graphic to the ODF document, that it is viewable: 

 
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathFactory;
import org.openoffice.odf.doc.OdfDocument;
import org.openoffice.odf.dom.element.text.OdfParagraphElement;
import org.openoffice.odf.dom.OdfNamespace;
import org.w3c.dom.Document;
[...]

// loads the ODF document from the path
OdfDocument odfDoc = OdfDocument.load("/home/myDocuments/myVacation.odt");

// get the ODF content as DOM tree representation
OdfFileDom odfContent = odfDoc.getContentDom();

//// W3C XPath initialization ''(JDK5 functionality)''  - XPath is the path within the XML file
//// (Find XPath examples here: http://www.w3.org/TR/xpath#path-abbrev)
XPath xpath = XPathFactory.newInstance().newXPath();
xpath.setNamespaceContext(new OdfNamespace());

// receiving the first paragraph "//text:p[1]" ''(JDK5 functionality)''
OdfParagraphElement para = (OdfParagraphElement) xpath.evaluate("//text:p[1]", odfContent, XPathConstants.NODE);

// adding an image - expecting the user to know that 
// an image consists always of a 'draw:image' and a 'draw:frame' parent

// FUTURE USAGE: Child access methods are still not part of the v0.6.x releases
// para.createDrawFrame().createDrawImage("/myweb.org/images/myHoliday.png");

// CURRENT USAGE (NOTE: width & height is not set by convenient API):
OdfFrame odfFrame =  (OdfFrame) OdfElementFactory.createOdfElement(odfContent, OdfFrame.ELEMENT_NAME);
para.appendChild(odfFrame);
OdfImage odfImage = (OdfImage) OdfElementFactory.createOdfElement(odfContent, OdfImage.ELEMENT_NAME);
odfImage.insertImage(new URI("/myweb.org/images/myHoliday.png"));
odfFrame.appendChild(odfImage);
odfDoc.save("/home/myDocuments/myVacation.odt");


The ODF Document / Convenient Functionality Layer

The purpose of a class from the convenient layer is to provide a higher usability for the API user. To establish this a convenient layer class usually controls multiple XML elements representing a component. In contrary to this the classes from the previous XML layer only control their ODF element and its attributes.

For instance, the table class of the convenient layer manipulates not only the table element and its attributes, but may manipulate all table element children. For example, when adding a cell to a table not only a new table cell would be created, but as well row and column information on their elements might be updated. All this in a single method call at the table.

Usually a class from the Convenient Layer is derived from the covered XML layered class to inherit its DOM functionality.

As naming convention all sources of the ODF document / convenient functionality layer are organized beyond org.openoffice.odf.doc.* The name of a convenient class is similar as it's parent from the XML layer, only the suffix 'Element' has been neglected.

For example, the convenient class for a 'draw:frame' element would be represented in the ODFDOM Java reference implemenation as org.openoffice.odf.doc.draw.OdfFrame class.


The Customized ODF Document / Extendable Layer

Although not part of the ODFDOM package it is designed as a layer on top of ODFDOM, where customer are able to replace/overwrite/customize ODF elements.

For instance, change the default size/style of their new tables.


Current and Future Work

The current ODFDOM is based on Java 5. The Mercurial repository is available here. A binary release and and the JavaDoc API documentation is available in the download area.

Especially the convenient layer will grow on demand. As ODFDOM should be the basement of many future ODF projects, a high quality is desired. Therefore automatic tests are obligatory for all new sources of the Java reference implementation.

The development is being discussed on the dev mailing list and in the ODFDOM forum.

ODFDOM Code Generator

The ODFDOM Code Generator is used to generate the core Classes for ODFDOM which are a typed mapping of the ODF elements on real Java Classes. For the future we also plan to generate ODFDOM e.g. C# ( .NET ) for other programming languages with this generator. Take a look at this page (ODFDOM Code Generator) to see how the generator works.

Back to: ODF Toolkit Wiki Home