How to use Low Level CTRPr & CTPPr Classes of latest Apache POI 5.2.2

Question

I am upgrading to latest POI 5.2.2 from POI 3.14. Currently I am using below mentioned low level classes in Apace POI 3.14 which needs to be updated.

i)CTRPr - to set/get run props like bold, italics, etc.. by API's like getBold(), getI(), etc.. in POI 3.14, but it seems API's to set/get bold, italics, are changed to handle list of values like getBList(),getIList(), setBArray(..), setIArray(..), etc.. in latest POI 5.2.2. Any run would only have 1 RPr in word xml & so API's like getBold() should be sufficient. Why latest API are utilizing List of values? How to use these latest API's in code & set various Run props ?

ii)CTPPr - set/get Para level Props of inline paras, list, etc.. using CTLvl level.getPpr() returns CTPpr Class in POI 3.14, but CTLvl level.getPpr() returns CTPPrGeneral class in POI 5.2.2 eventhough all ParaProps are still present in CTPpr class but why is CTPPrGeneral class returned instead of CTPpr ? What is use of it ? How to utilise latest API's in code & set various Para props ?

Any answer with detailed info reg this will be really helpful.

Answer 1

Office Open XML-schemas classes are generated form XSD files which are published in ECMA-376. They are contained in download part 4. The XSDs contain definitions for the XML which gets used in Office Open XML. XMLBeans from Apache provides methods to auto-generate Java classes from this XSDs. So the low-level Office Open XML-schemas classes of ooxml-schemas or poi-ooxml-lite or poi-ooxml-full do fully translate the given XSD definitions to Java.

So the general answer to your question about the reason of changes in this Office Open XML-schemas classes is that the published XSDs have changed from 1st edition in 2006 up to 4th edition in 2012. Or the used XMLBeans version has changed and does the XSD - Java - translation a little bit different.

CTRPr - set/get-methods - one element versus lists

In 1st edition of wml.xsd the CT_RPr was defined as a sequence of EG_RPrContent where EG_RPrContent is a sequence of EG_RPrBase having minOccurs="0". This means EG_RPrBase doresn't have to occur but can occur. The EG_RPrBase then contains all the definitions of the possible run properties. This was interpreted so, that CT_RPr might have either none or each of the possible run properties of EG_RPrBase once.

Now in 4th edition of wml.xsd the CT_RPr is defined as above but EG_RPrContent is a sequence of EG_RPrBase having minOccurs="0" and maxOccurs="unbounded". This means EG_RPrBase doresn't have to occur but can occur and if it occurs, then either once or multiple times. This can only be interpreted so, that CT_RPr might have either none or each of the possible run properties of EG_RPrBase even multiple times. That's why the lists now.

CTLvl.getPpr() returns CTPpr versus CTPPrGeneral class

In 1th edition of wml.xsd the CT_Lvl element was defined having following sub-element:

<xsd:element name="pPr" type="CT_PPr" minOccurs="0">
  <xsd:annotation>
    <xsd:documentation>Numbering Level Associated Paragraph Properties</xsd:documentation>
  </xsd:annotation>
</xsd:element>

There was not even a definition of CT_PPrGeneral. So CTLvl.getPpr() must return CTPpr.

Now in 4th edition of wml.xsd the CT_Lvl element is defined having following sub-element:

<xsd:element name="pPr" type="CT_PPrGeneral" minOccurs="0"/>

So CTLvl.getPpr() must return CTPPrGeneral now. But CTPPrGeneral provides most possibilities which CTPpr also has since also CT_PPrGeneral provides most possibilities which CT_Ppr also provides except CT_ParaRPr and CT_SectPr.

And since the 4th edition of wml.xsd also still defines the CT_Ppr element, CTPpr is also needed in Java. So CTPPrGeneral does not replace CTPpr in Java since also CT_PPrGeneral does not replaces CT_Ppr in XSD.