start process of introducing an interface for Comments Table

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

src/ooxml/java/org/apache/poi/xssf/eventusermodel/XSSFSheetXMLHandler.java

@@ -27,6 +27,7 @@ import org.apache.poi.ss.usermodel.RichTextString;
 import org.apache.poi.ss.util.CellAddress;
 import org.apache.poi.util.POILogFactory;
 import org.apache.poi.util.POILogger;
+import org.apache.poi.xssf.model.Comments;
 import org.apache.poi.xssf.model.CommentsTable;
 import org.apache.poi.xssf.model.SharedStrings;
 import org.apache.poi.xssf.model.StylesTable;
@@ -68,7 +69,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
    /**
     * Table with cell comments
     */
-   private CommentsTable commentsTable;
+   private Comments comments;
 
    /**
     * Read only access to the shared strings table, for looking
@@ -124,13 +125,13 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
            DataFormatter dataFormatter,
            boolean formulasNotResults) {
        this.stylesTable = styles;
-       this.commentsTable = comments;
+       this.comments = comments;
        this.sharedStringsTable = strings;
        this.output = sheetContentsHandler;
        this.formulasNotResults = formulasNotResults;
        this.nextDataType = xssfDataType.NUMBER;
        this.formatter = dataFormatter;
-       init();
+       init(comments);
    }
    
    /**
@@ -162,7 +163,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
        this(styles, strings, sheetContentsHandler, new DataFormatter(), formulasNotResults);
    }
    
-   private void init() {
+   private void init(CommentsTable commentsTable) {
        if (commentsTable != null) {
            commentCellRefs = new LinkedList<>();
            //noinspection deprecation
@@ -376,7 +377,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
            
            // Do we have a comment for this cell?
            checkForEmptyCellComments(EmptyCellCommentsCheckType.CELL);
-           XSSFComment comment = commentsTable != null ? commentsTable.findCellComment(new CellAddress(cellRef)) : null;
+           XSSFComment comment = comments != null ? comments.findCellComment(new CellAddress(cellRef)) : null;
            
            // Output
            output.cell(cellRef, thisStr, comment);
@@ -490,7 +491,7 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
     * Output an empty-cell comment.
     */
    private void outputEmptyCellComment(CellAddress cellRef) {
-       XSSFComment comment = commentsTable.findCellComment(cellRef);
+       XSSFComment comment = comments.findCellComment(cellRef);
        output.cell(cellRef.formatAsString(), null, comment);
    }
    
@@ -506,10 +507,10 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
     */
    public interface SheetContentsHandler {
       /** A row with the (zero based) row number has started */
-      public void startRow(int rowNum);
+      void startRow(int rowNum);
 
       /** A row with the (zero based) row number has ended */
-      public void endRow(int rowNum);
+      void endRow(int rowNum);
 
       /**
        * A cell, with the given formatted value (may be null), 
@@ -520,12 +521,12 @@ public class XSSFSheetXMLHandler extends DefaultHandler {
        * <code>src/examples/src/org/apache/poi/xssf/eventusermodel/XLSX2CSV.java</code>
        * for an example of how to handle this scenario.
        */
-      public void cell(String cellReference, String formattedValue, XSSFComment comment);
+      void cell(String cellReference, String formattedValue, XSSFComment comment);
 
       /** A header or footer has been encountered */
-      public default void headerFooter(String text, boolean isHeader, String tagName) {}
+      default void headerFooter(String text, boolean isHeader, String tagName) {}
 
       /** Signal that the end of a sheet was been reached */
-      public default void endSheet() {}
+      default void endSheet() {}
    }
 }

src/ooxml/java/org/apache/poi/xssf/extractor/XSSFBEventBasedExcelExtractor.java

@@ -97,7 +97,7 @@ public class XSSFBEventBasedExcelExtractor extends XSSFEventBasedExcelExtractor
             XSSFBCommentsTable comments,
             SharedStrings strings,
             InputStream sheetInputStream)
-            throws IOException, SAXException {
+            throws IOException {
 
         DataFormatter formatter;
         if (getLocale() == null) {

src/ooxml/java/org/apache/poi/xssf/extractor/XSSFEventBasedExcelExtractor.java

@@ -39,6 +39,7 @@ import org.apache.poi.xssf.eventusermodel.ReadOnlySharedStringsTable;
 import org.apache.poi.xssf.eventusermodel.XSSFReader;
 import org.apache.poi.xssf.eventusermodel.XSSFSheetXMLHandler;
 import org.apache.poi.xssf.eventusermodel.XSSFSheetXMLHandler.SheetContentsHandler;
+import org.apache.poi.xssf.model.Comments;
 import org.apache.poi.xssf.model.CommentsTable;
 import org.apache.poi.xssf.model.SharedStrings;
 import org.apache.poi.xssf.model.StylesTable;

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

@@ -0,0 +1,52 @@
+/* ====================================================================
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================== */
+package org.apache.poi.xssf.model;
+
+import org.apache.poi.ss.util.CellAddress;
+import org.apache.poi.xssf.usermodel.XSSFComment;
+
+/**
+ * An interface exposing useful functions for dealing with Excel Workbook Comments.
+ * It is intended that this interface should support low level access and not expose
+ * all the comments in memory
+ */
+public interface Comments {
+
+    int getNumberOfComments();
+
+    int getNumberOfAuthors();
+
+    String getAuthor(long authorId);
+
+    int findAuthor(String author);
+
+    /**
+     * Finds the cell comment at cellAddress, if one exists
+     *
+     * @param cellAddress the address of the cell to find a comment
+     * @return cell comment if one exists, otherwise returns null
+     */
+    XSSFComment findCellComment(CellAddress cellAddress);
+
+    /**
+     * Remove the comment at cellRef location, if one exists
+     *
+     * @param cellRef the location of the comment to remove
+     * @return returns true if a comment was removed
+     */
+    boolean removeComment(CellAddress cellRef);
+}

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

@@ -38,9 +38,11 @@ import org.openxmlformats.schemas.spreadsheetml.x2006.main.CTComments;
 import org.openxmlformats.schemas.spreadsheetml.x2006.main.CommentsDocument;
 
 @Internal
-public class CommentsTable extends POIXMLDocumentPart {
+public class CommentsTable extends POIXMLDocumentPart implements Comments {
+
     public static final String DEFAULT_AUTHOR = "";
     public static final int DEFAULT_AUTHOR_ID = 0;
+
     /**
      * Underlying XML Beans CTComment list.
      */
@@ -75,6 +77,7 @@ public class CommentsTable extends POIXMLDocumentPart {
             throw new IOException(e.getLocalizedMessage());
         }
     }
+
     public void writeTo(OutputStream out) throws IOException {
         CommentsDocument doc = CommentsDocument.Factory.newInstance();
         doc.setComments(comments);
@@ -102,18 +105,22 @@ public class CommentsTable extends POIXMLDocumentPart {
        }
     }
 
+    @Override
     public int getNumberOfComments() {
         return comments.getCommentList().sizeOfCommentArray();
     }
 
+    @Override
     public int getNumberOfAuthors() {
         return comments.getAuthors().sizeOfAuthorArray();
     }
 
+    @Override
     public String getAuthor(long authorId) {
         return comments.getAuthors().getAuthorArray((int)authorId);
     }
 
+    @Override
     public int findAuthor(String author) {
         String[] authorArray = comments.getAuthors().getAuthorArray();
         for (int i = 0 ; i < authorArray.length; i++) {
@@ -130,6 +137,7 @@ public class CommentsTable extends POIXMLDocumentPart {
      * @param cellAddress the address of the cell to find a comment
      * @return cell comment if one exists, otherwise returns null
      */
+    @Override
     public XSSFComment findCellComment(CellAddress cellAddress) {
         CTComment ct = getCTComment(cellAddress);
         return ct == null ? null : new XSSFComment(this, ct, null);
@@ -205,6 +213,7 @@ public class CommentsTable extends POIXMLDocumentPart {
      * @param cellRef the location of the comment to remove
      * @return returns true if a comment was removed
      */
+    @Override
     public boolean removeComment(CellAddress cellRef) {
         final String stringRef = cellRef.formatAsString();
         CTCommentList lst = comments.getCommentList();

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

@@ -48,7 +48,7 @@ public interface SharedStrings {
      * @param idx index of item to return.
      * @return the item at the specified position in this Shared String table.
      */
-    public RichTextString getItemAt(int idx);
+    RichTextString getItemAt(int idx);
 
     /**
      * Return an integer representing the total count of strings in the workbook. This count does not
@@ -56,7 +56,7 @@ public interface SharedStrings {
      *
      * @return the total count of strings in the workbook
      */
-    public int getCount();
+    int getCount();
 
     /**
      * Returns an integer representing the total count of unique strings in the Shared String Table.
@@ -65,5 +65,5 @@ public interface SharedStrings {
      *
      * @return the total count of unique strings in the workbook
      */
-    public int getUniqueCount();
+    int getUniqueCount();
 }