[WebODF] apache odfdom/Simple API

[Jos van den Oever]

On 09/27/13 21:39, Tobias Hintze wrote:
> I just stumbled again over:
> http://incubator.apache.org/odftoolkit
>
> Which has ODFDOM and this Simple API, which I did not notice before:
>
> http://incubator.apache.org/odftoolkit/simple/document/index.html
>
> It comes with the respective javadoc for API:
> http://incubator.apache.org/odftoolkit/simple/document/javadoc/index.html
>
> and a nice cookbook like set of examples:
> http://incubator.apache.org/odftoolkit/simple/document/cookbook/index.html
>
>
> Perhaps it makes sense to align with this API.
>
> set*, apply* et al might map to Operations in our universe, while
> the getter-functions show the lack of the analogy within WebODF.
>
> (While Operations for changing a document are one part. There is a
>   similar need for the opposite (getting data out of a document.))

A logical structured API for WebODF document creation is a good idea.
Our operations are a good start. Wrapping them in convenient functions 
is a good idea.

I looked at one example from the cookbook:

             TextDocument document = TextDocument.newTextDocument();

             Table table1 = Table.newTable(document);

             table1.setTableName("table1");

             document.save(filePath);

That is awfully short. Reading the API docs for newTable, I see that the 
explanation is pretty good and the implementation makes sense.

[1] 
http://incubator.apache.org/odftoolkit/mvn-site/0.8-incubating/simple-odf/apidocs/org/odftoolkit/simple/table/Table.html#newTable(org.odftoolkit.simple.table.TableContainer)

I think adopting this API is a good idea, but a lot of work. Also, I 
think it should be implemented via our operations and in a separate 
namespace. We might implement different apis in the future.

Ideally the function calls would be grouped operations themselves. This 
makes undo/redo and collaborative editing easier.

A challenge is to make the objects in the api aware of the other 
operations that may run and invalidate these objects. Having some local 
increasing version number in the document might be a way to handle that. 
If the version is different from the last version number, the internals 
of the object should be updated.

Cheers,
Jos