org.apache.poi.xssf.usermodel

## Class XSSFTable

- java.lang.Object
- - org.apache.poi.ooxml.POIXMLDocumentPart
  - - org.apache.poi.xssf.usermodel.XSSFTable

- All Implemented Interfaces:
    Table

      public class XSSFTable
      extends 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.
  Author:
    Roberto Manicardi

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.poi.ooxml.POIXMLDocumentPart

      `POIXMLDocumentPart.RelationPart`

  - ### Field Summary

    - ### Fields inherited from interface org.apache.poi.ss.usermodel.Table

      `isStructuredReference`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XSSFTable()` empty implementation, not attached to a workbook/worksheet yet
    `XSSFTable(PackagePart part)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `commit()` Save the content in the underlying package part.
    `boolean` | `contains(CellReference cell)` checks if the given cell is part of the table.
    `XSSFTableColumn` | `createColumn(java.lang.String columnName)` Add a new column to the right end of the table.
    `XSSFTableColumn` | `createColumn(java.lang.String columnName, int columnIndex)` Adds a new column to the table.
    `int` | `findColumnIndex(java.lang.String columnHeader)` Gets the relative column index of a column in this table having the header name `column`.
    `AreaReference` | `getArea()` Get the area that this table covers.
    `AreaReference` | `getCellReferences()` Get the area reference for the cells which this table covers.
    `int` | `getColumnCount()` Get the total number of columns in this table.
    `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()`
    `java.lang.String` | `getCommonXpath()` Calculates the xpath of the root element for the table.
    `org.openxmlformats.schemas.spreadsheetml.x2006.main.CTTable` | `getCTTable()` get the underlying CTTable XML bean
    `int` | `getDataRowCount()` Get the number of data rows in this table.
    `java.lang.String` | `getDisplayName()`
    `CellReference` | `getEndCellReference()`
    `int` | `getEndColIndex()` Get the bottom-right column index on the sheet
    `int` | `getEndRowIndex()` Get the bottom-right row index
    `int` | `getHeaderRowCount()`
    `java.lang.String` | `getName()` Get the name of the table.
    `long` | `getNumberOfMappedColumns()` Deprecated. Use `getColumnCount()` instead.
    `int` | `getRowCount()` Get the total number of rows in this table, including all header rows and all totals rows.
    `java.lang.String` | `getSheetName()` Returns the sheet name that the table belongs to.
    `CellReference` | `getStartCellReference()`
    `int` | `getStartColIndex()` Get the top-left column index relative to the sheet
    `int` | `getStartRowIndex()` Get the top-left row index on the sheet
    `TableStyleInfo` | `getStyle()`
    `java.lang.String` | `getStyleName()`
    `int` | `getTotalsRowCount()`
    `java.util.List<XSSFXmlColumnPr>` | `getXmlColumnPrs()` Deprecated. Use `XSSFTableColumn.getXmlColumnPr()` instead.
    `XSSFSheet` | `getXSSFSheet()`
    `boolean` | `isHasTotalsRow()` Note: This is misleading.
    `boolean` | `mapsTo(long id)` Checks if this Table element contains even a single mapping to the map identified by id
    `protected void` | `onTableDelete()` Remove relations
    `void` | `readFrom(java.io.InputStream is)` Read table XML from an `InputStream`
    `void` | `removeColumn(int columnIndex)` Remove a column from the table.
    `void` | `removeColumn(XSSFTableColumn column)` Remove a column from the table.
    `void` | `setArea(AreaReference tableArea)` Set the area reference for the cells which this table covers.
    `protected void` | `setCellRef(AreaReference refs)`
    `void` | `setCellReferences(AreaReference refs)` Set the area reference for the cells which this table covers.
    `void` | `setDataRowCount(int newDataRowCount)` Set the number of rows in the data area of the table.
    `void` | `setDisplayName(java.lang.String name)` Changes the display name of the Table
    `void` | `setName(java.lang.String newName)` Changes the name of the Table
    `void` | `setStyleName(java.lang.String newStyleName)` Changes the name of the Table
    `void` | `updateHeaders()` Synchronize table headers with cell values in the parent sheet.
    `void` | `updateReferences()` Clears the cached values set by `getStartCellReference()` and `getEndCellReference()`.
    `void` | `writeTo(java.io.OutputStream out)` write table XML to an `OutputStream`

    - ### Methods inherited from class org.apache.poi.ooxml.POIXMLDocumentPart

      `_invokeOnDocumentRead, addRelation, createRelationship, createRelationship, createRelationship, getNextPartNumber, getPackagePart, getParent, getRelationById, getRelationId, getRelationPartById, getRelationParts, getRelations, getTargetPart, isCommited, isCommitted, onDocumentCreate, onDocumentRead, onDocumentRemove, onSave, prepareForCommit, read, rebase, removeRelation, removeRelation, removeRelation, setCommited, setCommitted, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.poi.ss.usermodel.Table

      `contains`

- - ### 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.

    - #### commit

          protected void commit()
                         throws java.io.IOException

      Description copied from class: `POIXMLDocumentPart`
      Save the content in the underlying package part. Default implementation is empty meaning that the package part is left unmodified.

      Sub-classes should override and add logic to marshal the "model" into Ooxml4J.

      For example, the code saving a generic XML entry may look as follows:

           protected void commit() throws IOException {
             PackagePart part = getPackagePart();
             OutputStream out = part.getOutputStream();
             XmlObject bean = getXmlBean(); //the "model" which holds changes in memory
             bean.save(out, DEFAULT_XML_OPTIONS);
             out.close();
           }

      Overrides:
        `commit` in class `POIXMLDocumentPart`
      Throws:
        `java.io.IOException` - a subclass may throw an IOException if the changes can't be committed

    - #### getCTTable

          @Internal(since="POI 3.15 beta 3")
          public org.openxmlformats.schemas.spreadsheetml.x2006.main.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

    - #### getXmlColumnPrs

          @Deprecated
           @Removal(version="4.2.0")
          public java.util.List<XSSFXmlColumnPr> getXmlColumnPrs()

      Deprecated. Use `XSSFTableColumn.getXmlColumnPr()` instead.
      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 XSSFXmlColumnPr

    - #### 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"

    - #### setCellRef

          @Internal
          protected void setCellRef(AreaReference refs)

    - #### 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()`.

    - #### updateReferences

          public void updateReferences()

      Clears the cached values set by `getStartCellReference()` and `getEndCellReference()`. The next call to `getStartCellReference()` and `getEndCellReference()` will synchronize the cell references with the underlying `CTTable`. Thus this method is inexpensive.
      Since:
        POI 3.15 beta 3

    - #### 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)`

    - #### onTableDelete

          protected void onTableDelete()

      Remove relations

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.