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 Thu, 01 Mar 2012 10:07:45 GMT
Strictly speaking, someone is able to load a document alone with the ODF
Package API.
The base class of ODF XML document is part of the package layer. I also
have improved the ODF 1.2 part3 spec during my work in the TC that it is
clear that even a package has documents.
In technical terms a document is adequate to a directory with a MIME type.

I interpreted his request to merge Simple API and ODFDOM by the request
to merge Simple API and ODFDOM DOC API.


On 01.03.2012 10:43, Devin Han wrote:
>  Answer your question “Who is claiming that those API are in general not
> required?”
> see comments from Jeremias Maerki:
> Hi Devin,
> just my 0.05CHF:
> .... Some may not even need Simple at all. .....
> I drafted this proposal, just hope ODFDOM users still have an easy way to
> load ODF Document.
> Keep class OdfDocument is a way, but that will lead to code duplicated. As
> you know, Simple API also has class Document, which is very similar with
> OdfDocument.
> So, ODFDOM uses Simple API to load document is the best way. That means
> ODFDOM depends on Simple API, while Simple API depends on ODFDOM. Why not
> put them together?
> 2012/2/29 Svante Schubert <>
>> 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

View raw message