[dev] ODFDOM API Changes on branch odf-codegen (reactivating ODF code generation)

Dear all,

I have tested (as previously described) JApiCmp to identify the API changes
on the odf-codgen branch for ODF code generation
<https://github.com/tdf/odftoolkit/pull/182>.

The HTML report file
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html>
is
a bit noisy, as in the now updated code generation the base/super
class feature - for reuse of elements attributes and child elements -  had
been fixed.
The report is about 27 DINA4 pages long and I will highlight the reasons
for some changes.

Earlier API Problem: Visible after fix of Base Class Handling
As you can see from the grammar-additions.xml
<https://github.com/tdf/odftoolkit/blob/odf-codegen/generator/schema2template/src/test/resources/test-input/odf/generation/odfdom-java/dom/grammar-additions.xml>
file
there are 5 base classes being generated:

   1. DrawShapeBase (with 17 subclasses)
   2. NumberDataStyleBase (with 7 subclasses)
   3. TableTableCellBase (with 2 subclasses)
   4. TextListLevelStyle (with 3 subclasses)
   5. TextParagraphBase (with 2 subclasses)

I can not remember who had sent the requirements to those base classes but
I assume it was Sun's web office team.
There was a problem with the DrawShapBase in the previous API: if you
consult the previous JavaDoc
<https://odftoolkit.org/api/odfdom/org/odftoolkit/odfdom/dom/element/draw/DrawShapeElementBase.html>
you will notice method access to @svg:height attribute
<https://odftoolkit.org/api/odfdom/org/odftoolkit/odfdom/dom/element/draw/DrawShapeElementBase.html#getSvgHeightAttribute()>
but
you may find several subclasses (like for for <draw:connector>
<https://tdf.github.io/odftoolkit/odf1.3/OpenDocument-v1.3-reference.html#element_draw:connector_0>,
which does not offer such an attribute
<http://docs.oasis-open.org/office/OpenDocument/v1.3/os/schemas/OpenDocument-v1.3-schema-rng.html#draw-connector>).
That is the reason for the API removal mentioned within the HTML report for
the DrawShapeBaseElement
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html#org.odftoolkit.odfdom.dom.element.draw.DrawShapeElementBase>,
as now the base class generation was fixed.

On other occasions shared attributes & children were still in the
subclasses and have now been moved to the base class. But I guess this API
change should make no difference as the same functionality is being offered.
Nevertheless, the HTML report marks this as delete and new API and not as a
move of an API to its superclass (simply "text search" for it within the
report and you will notice its movement).

Nice2Have: The generation of Interfaces for semantic-groups
I had to fix the API due to the removal of svg:height and circumventing the
problem by accessing directly DOM API, but it would be nice to add
interfaces for those shapes sharing height/width attributes allowing
grouping and subclassing in the future. Uncertain how these
Interfaces could be easily found (perhaps even by some
heuristics/automation)? The definition in the RNG grammar file of ODF might
be a hint. A more general hint would be an RNG grammar analysis returning
the elements with the most shared attributes as Interface candidates.

Nice2Have: The generation of ODF element constructors with all mandatory
 info
This is something for "later" to offer a constructor for an ODF element
with all its mandatory attributes and those from the mandatory element
children, and so on...
But I already missed this feature... and removed the manually added
constructor from NumberBooleanStyleElement
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html#org.odftoolkit.odfdom.dom.element.number.NumberBooleanStyleElement>
!

API Problem: NumberTextStyleElement and NumberBooleanStyleElement
I hate to say it, but it was probably me!
All other data styles were abstract and convenience API was added by
inheriting from the ODF convenience class (e.g. ), but not for the
NumberTextStyleElement
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html#org.odftoolkit.odfdom.dom.element.number.NumberTextStyleElement>
and NumberBooleanStyleElement
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html#org.odftoolkit.odfdom.dom.element.number.NumberBooleanStyleElement>,
where I added the functionality once in the generated code. I made it
consistent some weeks ago by making those two elements abstract and adding
a new subclass below before I adopted the generated to insert such
functionality on demand.
If this is already too annoying for you, I might be willing to turn this
change back. Sorry for any inconvenience!

No API Problem: Removal getValue() / setValue()
The deletion of these getValue()/setValue() methods
<https://svanteschubert.github.io/odftoolkit/api/ODFDOM_API_CHANGES_odf-codgen_branch.html#org.odftoolkit.odfdom.pkg.manifest.InitialisationVectorAttribute>,
which were earlier generated but are identical with methods provided by
Xerces XML parser implementation. There should be no problem!
For instance, the current getValue() of InitialisationVectorAttribute
<https://odftoolkit.org/api/odfdom/org/odftoolkit/odfdom/pkg/manifest/InitialisationVectorAttribute.html#getValue()>
will
be replaced by its inherited getValue() of AttrImpl (Xerces)
<https://xerces.apache.org/xerces-j/apiDocs/org/apache/xerces/dom/AttrImpl.html#getValue()>
as
you can see in the latest JavaDoc of InitialisationVectorAttribute
<https://svanteschubert.github.io/odftoolkit/api/odfdom/org/odftoolkit/odfdom/pkg/manifest/InitialisationVectorAttribute.html>
.

Any new API added and listed is not a problem!

Should there be any further changes/problems in the report I have noticed
or in case you have any further suggestions, please drop me a line!
Perhaps there are already unknown better tooling for Java API changes out
there unnoticed?

Thanks,
Svante

-- 
To unsubscribe e-mail to: dev+unsubscribe@odftoolkit.org
Problems? https://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: https://wiki.documentfoundation.org/Netiquette
List archive: https://listarchives.odftoolkit.org/dev/
Privacy Policy: https://www.documentfoundation.org/privacy