Frequently Asked Questions

For Users

How to download and install

You can get Simple Java API for ODF as binary distribution from the download area. There you'll find Javadocs as well. To obtain source code, please refer to development section.

How to start development

I suggest you to start from an overview of this project. This page will give you an overall introduction of the package structures. After that, you can go to the Cookbook and Demos to read some code samples. And then, you can start your own program to manipulate ODF document.

If you are familar with ODFDOM, Here are the API changes from ODFDOM.


In addition to the Simple Java API JAR file you will need to download and install the following runtime prerequisite:

Code examples
You can find sample codes from our Cookbook and Demos.

How to report defects
The Simple API uses Bugzilla to track the defects. You can report defects here.

For Developers

How to download source

First, install latest Mercurial
Second, setup Mercurial (optional):
Config file <Hg Install Dir>\Mercurial.ini on Windows or <Hg Install Dir>/.hgrc on Unix.
Enhance the default configuration, using GIT diff and enable default plugin avoid different line breaks in the source.

username = your Name <>
;merge = your-merge-program (or internal:merge)

git = 1

diff=-p -U 8

# Enables mercurial EOL extension for line break handling
# See (bundled since 1.5.4)
eol =

# It'll remove unknown files and empty directories by default. 
# Usually you call 'hg update -C' and 'hg purge' in sequence
# See  (bundled)

# Converts mixed line ending within a file to LF (Unix) format 
# before adding the file to the source repository
# See
only-consistent = False

Now, get the source code from the Simple project Mercurial repository. Please see below for a short introduction to using Mercurial on There's also a more general help on how to use source control systems on The command

hg clone

will download the repository into a new directory.

Please note that by this you'll get the latest changeset. If you for example want stable release 0.2, you may want to use

hg clone -r v0.2
Developers however always work on the latest changeset.

How to build and run the unit tests
After the source code is checked out, now get and install Apache Maven. On command line test your installation with "mvn -v".

If Maven is correctly installed, change into the project directory and build with command "mvn".


You can subscribe to the project's mailing lists from this page. The "users" list is for discussions about using the toolkit, and the "dev" list is for discussing the development of the toolkit. Active developers should also subscribe to the "commit" mailing list so they will receive those automatic notifications.

Easy entry level tasks


Design of the API

The design principle is "make it easy for users to locate the functions they want".

org.odftoolkit.simple.Document is the abstract base class which the specific document classes are derived from: TextDocument, SpreadsheetDocument, PresentationDocument, GraphicsDocument and ChartDocument.

For each document type we have a subpackage that contain additional classes related to that kind of documents. So org.odftoolkit.simple.chart has classes related to chart, org.odftoolkit.simple.text has classes related to text content, and org.odftoolkit.simple.presentation has classes related to presentation documents.

Besides the packages for different document types, there are additional packages defined for important common ODF features which are available across all kinds of documents, such as table, meta and style.

There is another package named org.odftoolkit.simple.common, which contains functions that are not related with a specific document type nor a specific feature. For example, the text extractor functions are put in this package.

How to contribute patches

If you want to contribute a patch to this project, following below steps:

How to review patches

As a reviewer, you need to carefully read the source code, run the unit tests, to make sure the new contributed code won't hurt the quality of this project.

Reference material


The current draft of the OASIS ODF 1.2 standard can be downloaded here.

Commands line tools

Powered by the Apache CMS.

Apache "ODF Toolkit" is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Copyright © 2011 The Apache Software Foundation Licensed under the Apache License, Version 2.0. Contact Us
Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
Other names appearing on the site may be trademarks of their respective owners.