incubator-odf-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Devin Han <devin...@apache.org>
Subject Re: [PROPOSAL] Combine ODFDOM and Simple API
Date Wed, 29 Feb 2012 06:20:44 GMT
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:
http://incubator.apache.org/odftoolkit/odfdom/Layers.html
It describes the layers of ODFDOM. ODF Document API is what we want to
remove and replaced by Simple API.

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!
(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.
(4) About the combine javadoc. I just want to say, no people have rights to
stop a child to explore the Unknown! 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 ;)

BTW: change package name to org.apache.odftoolkit is in our todo list of
the second release, so take it easy.

2012/2/24 Svante Schubert <svante.schubert@gmail.com>

> 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
>
> http://www.oasis-open.org/committees/document.php?document_id=45161&wg_abbrev=office-collab
>
> > (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
>
>


-- 
-Devin

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