Bug-61906 add API for working with RichStringText and deprecate API methods that use CTRst

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1818247 13f79535-47bb-0310-9956-ffa450edef68

src/ooxml/java/org/apache/poi/xssf/model/SharedStringsTable.java

@@ -31,6 +31,9 @@ import java.util.Map;
 
 import org.apache.poi.POIXMLDocumentPart;
 import org.apache.poi.openxml4j.opc.PackagePart;
+import org.apache.poi.ss.usermodel.RichTextString;
+import org.apache.poi.util.Removal;
+import org.apache.poi.xssf.usermodel.XSSFRichTextString;
 import org.apache.xmlbeans.XmlException;
 import org.apache.xmlbeans.XmlOptions;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRst;
@@ -140,11 +143,23 @@ public class SharedStringsTable extends POIXMLDocumentPart {
      *
      * @param idx index of item to return.
      * @return the item at the specified position in this Shared String table.
+     * @deprecated use <code>addSharedStringItem(RichTextString string)</code> instead
      */
+    @Removal(version = "4.2")
     public CTRst getEntryAt(int idx) {
         return strings.get(idx);
     }
 
+    /**
+     * Return a string item by index
+     *
+     * @param idx index of item to return.
+     * @return the item at the specified position in this Shared String table.
+     */
+    public RichTextString getItemAt(int idx) {
+        return new XSSFRichTextString(strings.get(idx));
+    }
+
     /**
      * Return an integer representing the total count of strings in the workbook. This count does not
      * include any numbers, it counts only the total of text strings in the workbook.
@@ -167,7 +182,7 @@ public class SharedStringsTable extends POIXMLDocumentPart {
     }
 
     /**
-     * Add an entry to this Shared String table (a new value is appened to the end).
+     * Add an entry to this Shared String table (a new value is appended to the end).
      *
      * <p>
      * If the Shared String table already contains this <code>CTRst</code> bean, its index is returned.
@@ -176,7 +191,9 @@ public class SharedStringsTable extends POIXMLDocumentPart {
      *
      * @param st the entry to add
      * @return index the index of added entry
+     * @deprecated use <code>addSharedStringItem(RichTextString string)</code> instead
      */
+    @Removal(version = "4.2")
     public int addEntry(CTRst st) {
         String s = getKey(st);
         count++;
@@ -193,15 +210,50 @@ public class SharedStringsTable extends POIXMLDocumentPart {
         strings.add(newSt);
         return idx;
     }
+
+    /**
+     * Add an entry to this Shared String table (a new value is appended to the end).
+     *
+     * <p>
+     * If the Shared String table already contains this string entry, its index is returned.
+     * Otherwise a new entry is added.
+     * </p>
+     *
+     * @param string the entry to add
+     * @since POI 4.0.0
+     * @return index the index of added entry
+     */
+    public int addSharedStringItem(RichTextString string) {
+        if(!(string instanceof XSSFRichTextString)){
+            throw new IllegalArgumentException("Only XSSFRichTextString argument is supported");
+        }
+        return addEntry(((XSSFRichTextString) string).getCTRst());
+    }
+
     /**
      * Provide low-level access to the underlying array of CTRst beans
      *
      * @return array of CTRst beans
+     * @deprecated use <code>getSharedStringItems</code> instead
      */
+    @Removal(version = "4.2")
     public List<CTRst> getItems() {
         return Collections.unmodifiableList(strings);
     }
 
+    /**
+     * Provide access to the strings in the SharedStringsTable
+     *
+     * @return list of shared string instances
+     */
+    public List<RichTextString> getSharedStringItems() {
+        ArrayList<RichTextString> items = new ArrayList<>();
+        for (CTRst rst : strings) {
+            items.add(new XSSFRichTextString(rst));
+        }
+        return Collections.unmodifiableList(items);
+    }
+
     /**
      * Write this table out as XML.
      * 

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFCell.java

@@ -450,7 +450,7 @@ public final class XSSFCell implements Cell {
                     _cell.setT(STCellType.S);
                     XSSFRichTextString rt = (XSSFRichTextString)str;
                     rt.setStylesTableReference(_stylesSource);
-                    int sRef = _sharedStringSource.addEntry(rt.getCTRst());
+                    int sRef = _sharedStringSource.addSharedStringItem(rt);
                     _cell.setV(Integer.toString(sRef));
                 }
                 break;
@@ -966,7 +966,7 @@ public final class XSSFCell implements Cell {
                     String str = convertCellValueToString();
                     XSSFRichTextString rt = new XSSFRichTextString(str);
                     rt.setStylesTableReference(_stylesSource);
-                    int sRef = _sharedStringSource.addEntry(rt.getCTRst());
+                    int sRef = _sharedStringSource.addSharedStringItem(rt);
                     _cell.setV(Integer.toString(sRef));
                 }
                 _cell.setT(STCellType.S);

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFFont.java

@@ -70,6 +70,7 @@ public class XSSFFont implements Font {
      *
      * @param font the underlying CTFont bean
      */
+    @Internal
     public XSSFFont(CTFont font) {
         _ctFont = font;
         _index = 0;
@@ -81,6 +82,7 @@ public class XSSFFont implements Font {
      * @param index font index
      * @param colorMap for default or custom indexed colors
      */
+    @Internal
     public XSSFFont(CTFont font, int index, IndexedColorMap colorMap) {
         _ctFont = font;
         _index = (short)index;
@@ -90,7 +92,7 @@ public class XSSFFont implements Font {
     /**
      * Create a new XSSFont. This method is protected to be used only by XSSFWorkbook
      */
-    protected XSSFFont() {
+    public XSSFFont() {
         this._ctFont = CTFont.Factory.newInstance();
         setFontName(DEFAULT_FONT_NAME);
         setFontHeight((double)DEFAULT_FONT_SIZE);

src/ooxml/java/org/apache/poi/xssf/usermodel/XSSFRichTextString.java

@@ -99,6 +99,7 @@ public class XSSFRichTextString implements RichTextString {
     /**
      * Create a rich text string from the supplied XML bean
      */
+    @Internal
     public XSSFRichTextString(CTRst st) {
         this.st = st;
     }
@@ -324,7 +325,7 @@ public class XSSFRichTextString implements RichTextString {
      *
      * @param s new string value
      */
-    public void setString(String s){
+    public void setString(String s) {
         clearFormatting();
         st.setT(s);
         preserveSpaces(st.xgetT());
@@ -496,7 +497,7 @@ public class XSSFRichTextString implements RichTextString {
      * @param   value the string to decode
      * @return  the decoded string
      */
-    static String utfDecode(String value){
+    static String utfDecode(String value) {
         if(value == null || !value.contains("_x")) {
             return value;
         }

src/ooxml/testcases/org/apache/poi/xssf/model/TestSharedStringsTable.java

@@ -27,6 +27,7 @@ import org.apache.poi.POIDataSamples;
 import org.apache.poi.ss.usermodel.Sheet;
 import org.apache.poi.ss.usermodel.Workbook;
 import org.apache.poi.xssf.XSSFTestDataSamples;
+import org.apache.poi.xssf.usermodel.XSSFFont;
 import org.apache.poi.xssf.usermodel.XSSFRichTextString;
 import org.apache.poi.xssf.usermodel.XSSFWorkbook;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTRElt;
@@ -42,6 +43,7 @@ import junit.framework.TestCase;
  */
 public final class TestSharedStringsTable extends TestCase {
 
+    @SuppressWarnings("deprecation")
     public void testCreateNew() {
         SharedStringsTable sst = new SharedStringsTable();
 
@@ -113,6 +115,72 @@ public final class TestSharedStringsTable extends TestCase {
         assertEquals("Second string", new XSSFRichTextString(sst.getEntryAt(2)).toString());
     }
 
+    public void testCreateUsingRichTextStrings() {
+        SharedStringsTable sst = new SharedStringsTable();
+
+        // Check defaults
+        assertNotNull(sst.getSharedStringItems());
+        assertEquals(0, sst.getSharedStringItems().size());
+        assertEquals(0, sst.getCount());
+        assertEquals(0, sst.getUniqueCount());
+
+        int idx;
+
+        XSSFRichTextString rts = new XSSFRichTextString("Hello, World!");
+
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(0, idx);
+        assertEquals(1, sst.getCount());
+        assertEquals(1, sst.getUniqueCount());
+
+        //add the same entry again
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(0, idx);
+        assertEquals(2, sst.getCount());
+        assertEquals(1, sst.getUniqueCount());
+
+        //and again
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(0, idx);
+        assertEquals(3, sst.getCount());
+        assertEquals(1, sst.getUniqueCount());
+
+        rts = new XSSFRichTextString("Second string");
+
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(1, idx);
+        assertEquals(4, sst.getCount());
+        assertEquals(2, sst.getUniqueCount());
+
+        //add the same entry again
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(1, idx);
+        assertEquals(5, sst.getCount());
+        assertEquals(2, sst.getUniqueCount());
+
+        rts = new XSSFRichTextString("Second string");
+        XSSFFont font = new XSSFFont();
+        font.setFontName("Arial");
+        font.setBold(true);
+        rts.applyFont(font);
+
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(2, idx);
+        assertEquals(6, sst.getCount());
+        assertEquals(3, sst.getUniqueCount());
+
+        idx = sst.addSharedStringItem(rts);
+        assertEquals(2, idx);
+        assertEquals(7, sst.getCount());
+        assertEquals(3, sst.getUniqueCount());
+
+        //OK. the sst table is filled, check the contents
+        assertEquals(3, sst.getSharedStringItems().size());
+        assertEquals("Hello, World!", sst.getItemAt(0).toString());
+        assertEquals("Second string", sst.getItemAt(1).toString());
+        assertEquals("Second string", sst.getItemAt(2).toString());
+    }
+
     public void testReadWrite() throws IOException {
         XSSFWorkbook wb1 = XSSFTestDataSamples.openSampleWorkbook("sample.xlsx");
         SharedStringsTable sst1 = wb1.getSharedStringSource();