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 <[email protected]> > 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
