incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Svante Schubert <>
Subject Re: [PROPOSAL] Combine ODFDOM and Simple API
Date Wed, 29 Feb 2012 14:23:04 GMT
We all agreed on deprecating the DOC API and continuing the Simple API
as both APIs are redundant to each other.
Before we remove the DOC API, we should be certain that we are not
removing a feature super set that is already being in use of developers.
Ashok announced yesterday to migrate, let us get feed-back from him
before deletion. In addition no DOC functionality (as the DOC tests)
should not be thrown away, but be moved to the Simple API.

More comments inline...

On 29.02.2012 07:20, Devin Han wrote:
> Hi all,
> I keep silence because I am waiting for the comments from somebody who have
> dived into the ODFDOM and Simple API source code. Unfortunately, nobody...
> Before read the following mail, please open this link:
> It describes the layers of ODFDOM. ODF Document API is what we want to
> remove and replaced by Simple API.
Not exactly nobody, 'cause I wrote the above documentation. (Changed is
only the background-color of the code examples, but be careful. The new
color might be an accessibility issue -  see
> What does the ODF Document API include? The right answer is that all of the
> classes in package "org.odftoolkit.odfdom.doc" and
> "org.odftoolkit.odfdom.incubator".
> What does it mean? That means not only Table API will be moved, but also
> OdfDocument, OdfTextDocument, OdfSpreadsheetDocument and etc. Does people,
> who said you didn't use ODFDOM Doc API or Simple API, can tell me how can
> you load an ODF document after the movement? You even can't use any dom
> element or attribute, because there is only an API support to load document
> as OdfPackageDocument. OdfPackageDocument knows nothing about dom element
> and attribute!
> You may say, I can realize a loadDocument method in OdfSchemaDocument. Yes,
> that can resolve the problem that how to use dom element and attribute. But
> you still don't know whether this document is a text document or a
> spreadsheet document.
> What I want to explain are 4 points:
> (1) All of us enjoy the convenience of ODFDOM Doc API or Simple API, but
> somebody say you don't need it!
Could you rephrase your point here, I do not fully understand. Who is
claiming that those API are in general not required?
> (2) The best way to resolve the problem after ODFDOM Doc API removed is
> Simple API.
> (3) Please think thing from the user view. Most of users don't care whether
> ODFDOM is designed as the three parts of ODF specification. They just want
> to manipulate ODF document easily! A so simple requirement, why we have to
> let them import so many jars? odfdom.jar is not enough, odfpackage.jar is
> also needed... In your opinion, it's resonable that JDK has to be separated
> in to lost of small jars, io.jar, util.jar, xml.jar... Could you tell me
> how many people use odfpackage.jar only? Please cost some time read the
> user mail list, most of questions are about Simple API, not odfpackage.jar.
> The report from Google Analytics also show Simple API is the most popular
> component of ODF Toolkit. Most people know ODFDOM, just because, Simple API
> needs it! But they have to download it separately and find the right
> version.
Not all users do care much about software design/modularization. For the
same reason the ODF specification part 3 had been split of from the main
spec, our library should be modularized.
In general the benefits are to split the complexity, decouple
unnecessary dependencies and to allow the user only to use (load/pay)
what is really needed. Avoiding memory overhead and boilerplate,
enabling a much more flexible design.
Even if 100% of the users on the list are using ODF XML it still makes
sense, as ODF 1.2 was designed to allow the independent usage of the
package, e.g. for audio books.
It is indeed a sad story, that the ePub standard (becoming an ISO
standard) is not reusing the ODF package, already. Those ePub ppl will
not write on the list, we have to work towards them to be adoptable.
Common users are no software developers. If someone only reacts to user
demands - without any adaption/refactoring of design/implementation -
the time to add features will grow, as the code becomes more difficult
to maintain, becoming unstable . Some ppl claim this happens with flash..

> (4) About the combine javadoc. I just want to say, no people have rights to
> stop a child to explore the Unknown! 
With the above argumentation, you may as well try to persuade us to jump
from a bridge. IMHO a little too much polemic, too little reasoning.
> We supply getOdfElement in most of
> Simple API classes. It possible that user want to know more about
> OdfElement and its subclasses and OdfAttribute. The combine javadoc supplys
> this way.
> Anyway, I have started the ODFDOM Doc API removement work. You will see the
> result later in the SVN. Any improvement suggestions are welcomed. Don't
> worry, I will not combine the two components before we get the consistent
> answer ;)
Perhaps it becomes a little more obvious, when I draft a vision:
IMHO the Simple API shall become the operations API that I plan to use
for ODF 1.3 change-tracking, see

For an advance scenario see:

Most likely the API will have to be adapted a little on new demands,
still it is worth the effort.
I got scenarios in mind, that here are currently not being questioned,
but I am aware are very much in need at very large companies (for the
ODF ecosystem in general), see

BTW the above examples not only work for collaboration, but should
become the lingua franca for ODF applications doing collaboration.
In addition the approach will not only allow automated merge on the
server (e.g. using ODF Toolkit), but history functions for ODF applications.

If you got comments on ODF 1.3, please state them directly to the ODF TC
as comment
due to IPR.

The above should make it more obvious, why it makes sense to divide the
Simple API (to be standardized) from the ODF XML API (redundant
functionality on a much fine granular implementation level).
To assist the user, I suggest instead to use JavaDoc Tags to provide a
reference from the Simple API JavaDoc to the ODFDOM API JavaDoc.
> BTW: change package name to org.apache.odftoolkit is in our todo list of
> the second release, so take it easy.
We all feel like Sunday morning.

- Svante
> 2012/2/24 Svante Schubert <>
>> On 23.02.2012 09:30, Devin Han wrote:
>>> Hi all,
>>> As you know we will remove the deprecated ODFDOM DOC layer and replace it
>>> with Simple API in the 2nd release. After that, ODFDOM will focus on low
>>> level dom/package layer, while Simple API focus on the high level
>>> convenient API. That would be a good news for users.
>>> Now, I have a new idea that why not combine ODFDOM and Simple API
>> together?
>>> If we do that, the advantages are:
>>> (1) The user only needs to download a single jar. Include to classpath
>>> easily and no need to care about the version dependency between ODFDOM
>> and
>>> Simple API.
>> I would rather got the opposite way and split ODFDOM into a odfdom.jar
>> and a odfpackage.jar to have a better modularization.
>> The ODF specification comes along with a three parts. ODF XML, ODF
>> formula and package for a reason. We should adapt the given modularity.
>> Still we might and should ODFDOM and Simple API join to provide a single
>> ZIP, as they belong semantically closer together as the other projects.
>> I do not see the download of multiple Jars as a problem.
>> Users tend to use build tools as Maven automated the download the jar or
>> download a jar only once. As mentioned we might even bundle jars to a
>> zip for manual download, as for instance Apache Xerces does.
>>> (2) ODFDOM and Simple API javadoc are together, user can find class,
>> method
>>> easily.
>> Quite the opposite. Simple API is called simple as you do only have such
>> a little powerful API calls, which bundle several DOM API calls.
>> If combine them, you will have again a jungle of an API.
>> In addition Simple and ODFDOM are different views on the model, we
>> should keep them separated.
>> Currently I am trying to evolve ODF operations to be serialized for ODF
>> change-tracking at OASIS.
>> In the end it is very close to the Simple API and should be later be
>> implemented as such, see
>>> (3) People, who only use ODFDOM before, has a chance to use Simple API to
>>> improve the efficiency. The jar of Simple API 0.7 is only 444.8 KB, would
>>> not take too much space.
>> I would indeed adapt our documentation / markering and put odfdom and
>> simple documentation closer together. Allow the jars and API being
>> downloaded as one, as they belong together.
>>> The questions are:
>>> (1) We need a new name for ODFDOM&Simple API.
>>> (2) What's the new package name of Simple API?  Inherit ODFDOM DOC Layer
>>> name or change nothing?
>> Therefore a mixed answer:
>> +1 for moving ODFDOM and Simple API closer together via wiki/website
>> documentation, Maven subproject and download bundle (ZIP)
>> -1 for moving ODFDOM and Simple API JavaDoc and JAR level together
>> - Svante

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message