Class XSSFTable

  • All Implemented Interfaces:
    Table

    public class XSSFTable
    extends org.apache.poi.ooxml.POIXMLDocumentPart
    implements Table
    This class implements the Table Part (Open Office XML Part 4: chapter 3.5.1) Columns of this table may contains mappings to a subtree of an XML. The root element of this subtree can occur multiple times (one for each row of the table). The child nodes of the root element can be only attributes or elements with maxOccurs=1 property set.
    • Constructor Detail

      • XSSFTable

        public XSSFTable()
        empty implementation, not attached to a workbook/worksheet yet
      • XSSFTable

        public XSSFTable​(PackagePart part)
                  throws java.io.IOException
        Parameters:
        part - The part used to initialize the table
        Throws:
        java.io.IOException - If reading data from the part fails.
        Since:
        POI 3.14-Beta1
    • Method Detail

      • readFrom

        public void readFrom​(java.io.InputStream is)
                      throws java.io.IOException
        Read table XML from an InputStream
        Parameters:
        is - The stream which provides the XML data for the table.
        Throws:
        java.io.IOException - If reading from the stream fails
      • getXSSFSheet

        public XSSFSheet getXSSFSheet()
        Returns:
        owning sheet
      • writeTo

        public void writeTo​(java.io.OutputStream out)
                     throws java.io.IOException
        write table XML to an OutputStream
        Parameters:
        out - The stream to write the XML data to
        Throws:
        java.io.IOException - If writing to the stream fails.
      • getCTTable

        @Internal(since="POI 3.15 beta 3")
        public CTTable getCTTable()
        get the underlying CTTable XML bean
        Returns:
        underlying OOXML object
      • mapsTo

        public boolean mapsTo​(long id)
        Checks if this Table element contains even a single mapping to the map identified by id
        Parameters:
        id - the XSSFMap ID
        Returns:
        true if the Table element contain mappings
      • getCommonXpath

        public java.lang.String getCommonXpath()
        Calculates the xpath of the root element for the table. This will be the common part of all the mapping's xpaths Note: this function caches the result for performance. To flush the cache updateHeaders() must be called.
        Returns:
        the xpath of the table's root element
      • getColumns

        public java.util.List<XSSFTableColumn> getColumns()
        Note this list is static - once read, it does not notice later changes to the underlying column structures To clear the cache, call updateHeaders()
        Returns:
        List of XSSFTableColumn
        Since:
        4.0.0
      • createColumn

        public XSSFTableColumn createColumn​(java.lang.String columnName)
        Add a new column to the right end of the table.
        Parameters:
        columnName - the unique name of the column, must not be null
        Returns:
        the created table column
        Since:
        4.0.0
      • createColumn

        public XSSFTableColumn createColumn​(java.lang.String columnName,
                                            int columnIndex)
        Adds a new column to the table.
        Parameters:
        columnName - the unique name of the column, or null for a generated name
        columnIndex - the 0-based position of the column in the table
        Returns:
        the created table column
        Throws:
        java.lang.IllegalArgumentException - if the column name is not unique or missing or if the column can't be created at the given index
        Since:
        4.0.0
      • removeColumn

        public void removeColumn​(XSSFTableColumn column)
        Remove a column from the table.
        Parameters:
        column - the column to remove
        Since:
        4.0.0
      • removeColumn

        public void removeColumn​(int columnIndex)
        Remove a column from the table.
        Parameters:
        columnIndex - the 0-based position of the column in the table
        Throws:
        java.lang.IllegalArgumentException - if no column at the index exists or if the table has only a single column
        Since:
        4.0.0
      • getName

        public java.lang.String getName()
        Description copied from interface: Table
        Get the name of the table.
        Specified by:
        getName in interface Table
        Returns:
        the name of the Table, if set
      • setName

        public void setName​(java.lang.String newName)
        Changes the name of the Table
        Parameters:
        newName - The name of the table.
      • getStyleName

        public java.lang.String getStyleName()
        Specified by:
        getStyleName in interface Table
        Returns:
        the table style name, if set
        Since:
        3.17 beta 1
      • setStyleName

        public void setStyleName​(java.lang.String newStyleName)
        Changes the name of the Table
        Parameters:
        newStyleName - The name of the style.
        Since:
        3.17 beta 1
      • getDisplayName

        public java.lang.String getDisplayName()
        Returns:
        the display name of the Table, if set
      • setDisplayName

        public void setDisplayName​(java.lang.String name)
        Changes the display name of the Table
        Parameters:
        name - to use
      • getNumberOfMappedColumns

        @Deprecated
        @Removal(version="4.2.0")
        public long getNumberOfMappedColumns()
        Deprecated.
        Use getColumnCount() instead.
        Returns:
        the number of mapped table columns (see Open Office XML Part 4: chapter 3.5.1.4)
      • getCellReferences

        public AreaReference getCellReferences()
        Get the area reference for the cells which this table covers. The area includes header rows and totals rows. Does not track updates to underlying changes to CTTable To synchronize with changes to the underlying CTTable, call updateReferences().
        Returns:
        the area of the table
        Since:
        3.17 beta 1
        See Also:
        "Open Office XML Part 4: chapter 3.5.1.2, attribute ref"
      • setCellReferences

        public void setCellReferences​(AreaReference refs)
        Set the area reference for the cells which this table covers. The area includes includes header rows and totals rows. Automatically synchronizes any changes by calling updateHeaders(). Note: The area's width should be identical to the amount of columns in the table or the table may be invalid. All header rows, totals rows and at least one data row must fit inside the area. Updating the area with this method does not create or remove any columns and does not change any cell values.
        Since:
        3.17 beta 1
        See Also:
        "Open Office XML Part 4: chapter 3.5.1.2, attribute ref"
      • setArea

        public void setArea​(AreaReference tableArea)
        Set the area reference for the cells which this table covers. The area includes includes header rows and totals rows. Updating the area with this method will create new column as necessary to the right side of the table but will not modify any cell values.
        Parameters:
        tableArea - the new area of the table
        Throws:
        java.lang.IllegalArgumentException - if the area is null or not
        Since:
        4.0.0
      • getArea

        public AreaReference getArea()
        Get the area that this table covers.
        Returns:
        the table's area or null if the area has not been initialized
        Since:
        4.0.0
      • getStartCellReference

        public CellReference getStartCellReference()
        Returns:
        The reference for the cell in the top-left part of the table (see Open Office XML Part 4: chapter 3.5.1.2, attribute ref) Does not track updates to underlying changes to CTTable To synchronize with changes to the underlying CTTable, call updateReferences().
      • getEndCellReference

        public CellReference getEndCellReference()
        Returns:
        The reference for the cell in the bottom-right part of the table (see Open Office XML Part 4: chapter 3.5.1.2, attribute ref) Does not track updates to underlying changes to CTTable To synchronize with changes to the underlying CTTable, call updateReferences().
      • getRowCount

        public int getRowCount()
        Get the total number of rows in this table, including all header rows and all totals rows. (Note: in this version autofiltering is ignored) Returns 0 if the start or end cell references are not set. Does not track updates to underlying changes to CTTable To synchronize with changes to the underlying CTTable, call updateReferences().
        Returns:
        the total number of rows
      • getDataRowCount

        public int getDataRowCount()
        Get the number of data rows in this table. This does not include any header rows or totals rows. Returns 0 if the start or end cell references are not set. Does not track updates to underlying changes to CTTable To synchronize with changes to the underlying CTTable, call updateReferences().
        Returns:
        the number of data rows
        Since:
        4.0.0
      • setDataRowCount

        public void setDataRowCount​(int newDataRowCount)
        Set the number of rows in the data area of the table. This does not affect any header rows or totals rows. If the new row count is less than the current row count, superfluous rows will be cleared. If the new row count is greater than the current row count, cells below the table will be overwritten by the table. To resize the table without overwriting cells, use setArea(AreaReference) instead.
        Parameters:
        newDataRowCount - new row count for the table
        Throws:
        java.lang.IllegalArgumentException - if the row count is less than 1
        Since:
        4.0.0
      • getColumnCount

        public int getColumnCount()
        Get the total number of columns in this table.
        Returns:
        the column count
        Since:
        4.0.0
      • updateHeaders

        public void updateHeaders()
        Synchronize table headers with cell values in the parent sheet. Headers must be in sync, otherwise Excel will display a "Found unreadable content" message on startup. If calling both updateReferences() and this method, updateReferences() should be called first. Note that a Table must have a header. To reproduce the equivalent of inserting a table in Excel without Headers, manually add cells with values of "Column1", "Column2" etc first.
      • findColumnIndex

        public int findColumnIndex​(java.lang.String columnHeader)
        Gets the relative column index of a column in this table having the header name column. The column index is relative to the left-most column in the table, 0-indexed. Returns -1 if column is not a header name in table. Column Header names are case-insensitive Note: this function caches column names for performance. To flush the cache (because columns have been moved or column headers have been changed), updateHeaders() must be called.
        Specified by:
        findColumnIndex in interface Table
        Parameters:
        columnHeader - the column header name to get the table column index of
        Returns:
        column index corresponding to columnHeader
        Since:
        3.15 beta 2
      • getSheetName

        public java.lang.String getSheetName()
        Description copied from interface: Table
        Returns the sheet name that the table belongs to.
        Specified by:
        getSheetName in interface Table
        Returns:
        sheet name
        Since:
        3.15 beta 2
      • isHasTotalsRow

        public boolean isHasTotalsRow()
        Note: This is misleading. The Spec indicates this is true if the totals row has ever been shown, not whether or not it is currently displayed. Use getTotalsRowCount() > 0 to decide whether or not the totals row is visible.
        Specified by:
        isHasTotalsRow in interface Table
        Returns:
        true if a totals row has ever been shown for this table
        Since:
        3.15 beta 2
        See Also:
        getTotalsRowCount()
      • getTotalsRowCount

        public int getTotalsRowCount()
        Specified by:
        getTotalsRowCount in interface Table
        Returns:
        0 for no totals rows, 1 for totals row shown. Values > 1 are not currently used by Excel up through 2016, and the OOXML spec doesn't define how they would be implemented.
        Since:
        3.17 beta 1
      • getHeaderRowCount

        public int getHeaderRowCount()
        Specified by:
        getHeaderRowCount in interface Table
        Returns:
        0 for no header rows, 1 for table headers shown. Values > 1 might be used by Excel for pivot tables?
        Since:
        3.17 beta 1
      • getStartColIndex

        public int getStartColIndex()
        Description copied from interface: Table
        Get the top-left column index relative to the sheet
        Specified by:
        getStartColIndex in interface Table
        Returns:
        table start column index on sheet
        Since:
        3.15 beta 2
      • getStartRowIndex

        public int getStartRowIndex()
        Description copied from interface: Table
        Get the top-left row index on the sheet
        Specified by:
        getStartRowIndex in interface Table
        Returns:
        table start row index on sheet
        Since:
        3.15 beta 2
      • getEndColIndex

        public int getEndColIndex()
        Description copied from interface: Table
        Get the bottom-right column index on the sheet
        Specified by:
        getEndColIndex in interface Table
        Returns:
        table end column index on sheet
        Since:
        3.15 beta 2
      • getEndRowIndex

        public int getEndRowIndex()
        Description copied from interface: Table
        Get the bottom-right row index
        Specified by:
        getEndRowIndex in interface Table
        Returns:
        table end row index on sheet
        Since:
        3.15 beta 2
      • getStyle

        public TableStyleInfo getStyle()
        Specified by:
        getStyle in interface Table
        Returns:
        TableStyleInfo for this instance
        Since:
        3.17 beta 1
      • contains

        public boolean contains​(CellReference cell)
        Description copied from interface: Table
        checks if the given cell is part of the table. Includes checking that they are on the same sheet.
        Specified by:
        contains in interface Table
        Parameters:
        cell - reference to a possibly undefined cell location
        Returns:
        true if the table and cell are on the same sheet and the cell is within the table range.
        Since:
        3.17 beta 1
        See Also:
        Table.contains(org.apache.poi.ss.usermodel.Cell)