Package 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
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
ConstructorsConstructorDescriptionempty implementation, not attached to a workbook/worksheet yetXSSFTable
(PackagePart part) -
Method Summary
Modifier and TypeMethodDescriptionprotected void
commit()
Save the content in the underlying package part.boolean
contains
(CellReference cell) checks if the given cell is part of the table.createColumn
(String columnName) Add a new column to the right end of the table.createColumn
(String columnName, int columnIndex) Adds a new column to the table.int
findColumnIndex
(String columnHeader) Gets the relative column index of a column in this table having the header namecolumn
.getArea()
Get the area that this table covers.Get the area reference for the cells which this table covers.int
Get the total number of columns in this table.Note this list is static - once read, it does not notice later changes to the underlying column structures To clear the cache, callupdateHeaders()
Calculates the xpath of the root element for the table.org.openxmlformats.schemas.spreadsheetml.x2006.main.CTTable
get the underlying CTTable XML beanint
Get the number of data rows in this table.int
Get the bottom-right column index on the sheetint
Get the bottom-right row indexint
getName()
Get the name of the table.long
Deprecated.int
Get the total number of rows in this table, including all header rows and all totals rows.Returns the sheet name that the table belongs to.int
Get the top-left column index relative to the sheetint
Get the top-left row index on the sheetgetStyle()
int
Deprecated.UseXSSFTableColumn.getXmlColumnPr()
instead.boolean
Note: This is misleading.boolean
mapsTo
(long id) Checks if this Table element contains even a single mapping to the map identified by idprotected void
Remove relationsvoid
readFrom
(InputStream is) Read table XML from anInputStream
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
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
(String name) Changes the display name of the Tablevoid
Changes the name of the Tablevoid
setStyleName
(String newStyleName) Changes the name of the Tablevoid
Synchronize table headers with cell values in the parent sheet.void
Clears the cached values set bygetStartCellReference()
andgetEndCellReference()
.void
writeTo
(OutputStream out) write table XML to anOutputStream
Methods inherited from class org.apache.poi.ooxml.POIXMLDocumentPart
_invokeOnDocumentRead, addRelation, createRelationship, createRelationship, createRelationship, getNextPartNumber, getPackagePart, getParent, getRelationById, getRelationId, getRelationPartById, getRelationParts, getRelations, getTargetPart, isCommited, onDocumentCreate, onDocumentRead, onDocumentRemove, onSave, prepareForCommit, read, rebase, removeRelation, removeRelation, removeRelation, setCommited, toString
-
Constructor Details
-
XSSFTable
public XSSFTable()empty implementation, not attached to a workbook/worksheet yet -
XSSFTable
- Parameters:
part
- The part used to initialize the table- Throws:
IOException
- If reading data from the part fails.- Since:
- POI 3.14-Beta1
-
-
Method Details
-
readFrom
Read table XML from anInputStream
- Parameters:
is
- The stream which provides the XML data for the table.- Throws:
IOException
- If reading from the stream fails
-
getXSSFSheet
- Returns:
- owning sheet
-
writeTo
write table XML to anOutputStream
- Parameters:
out
- The stream to write the XML data to- Throws:
IOException
- If writing to the stream fails.
-
commit
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 classPOIXMLDocumentPart
- Throws:
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
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 cacheupdateHeaders()
must be called.- Returns:
- the xpath of the table's root element
-
getColumns
Note this list is static - once read, it does not notice later changes to the underlying column structures To clear the cache, callupdateHeaders()
- Returns:
- List of XSSFTableColumn
- Since:
- 4.0.0
-
getXmlColumnPrs
Deprecated.UseXSSFTableColumn.getXmlColumnPr()
instead.Note this list is static - once read, it does not notice later changes to the underlying column structures To clear the cache, callupdateHeaders()
- Returns:
- List of XSSFXmlColumnPr
-
createColumn
Add a new column to the right end of the table.- Parameters:
columnName
- the unique name of the column, must not benull
- Returns:
- the created table column
- Since:
- 4.0.0
-
createColumn
Adds a new column to the table.- Parameters:
columnName
- the unique name of the column, ornull
for a generated namecolumnIndex
- the 0-based position of the column in the table- Returns:
- the created table column
- Throws:
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
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:
IllegalArgumentException
- if no column at the index exists or if the table has only a single column- Since:
- 4.0.0
-
getName
Description copied from interface:Table
Get the name of the table. -
setName
Changes the name of the Table- Parameters:
newName
- The name of the table.
-
getStyleName
- Specified by:
getStyleName
in interfaceTable
- Returns:
- the table style name, if set
- Since:
- 3.17 beta 1
-
setStyleName
Changes the name of the Table- Parameters:
newStyleName
- The name of the style.- Since:
- 3.17 beta 1
-
getDisplayName
- Returns:
- the display name of the Table, if set
-
setDisplayName
Changes the display name of the Table- Parameters:
name
- to use
-
getNumberOfMappedColumns
Deprecated.UsegetColumnCount()
instead.- Returns:
- the number of mapped table columns (see Open Office XML Part 4: chapter 3.5.1.4)
-
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, callupdateReferences()
.- Returns:
- the area of the table
- Since:
- 3.17 beta 1
- See Also:
-
setCellReferences
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 callingupdateHeaders()
. 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:
-
setCellRef
-
setArea
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:
IllegalArgumentException
- if the area isnull
or not- Since:
- 4.0.0
-
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
- 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
- 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 bygetStartCellReference()
andgetEndCellReference()
. The next call togetStartCellReference()
andgetEndCellReference()
will synchronize the cell references with the underlyingCTTable
. 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) Returns0
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, callupdateReferences()
.- 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. Returns0
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, callupdateReferences()
.- 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, usesetArea(AreaReference)
instead.- Parameters:
newDataRowCount
- new row count for the table- Throws:
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 bothupdateReferences()
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
Gets the relative column index of a column in this table having the header namecolumn
. The column index is relative to the left-most column in the table, 0-indexed. Returns-1
ifcolumn
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 interfaceTable
- 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
Description copied from interface:Table
Returns the sheet name that the table belongs to.- Specified by:
getSheetName
in interfaceTable
- 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. UsegetTotalsRowCount()
> 0 to decide whether or not the totals row is visible.- Specified by:
isHasTotalsRow
in interfaceTable
- Returns:
- true if a totals row has ever been shown for this table
- Since:
- 3.15 beta 2
- See Also:
-
getTotalsRowCount
public int getTotalsRowCount()- Specified by:
getTotalsRowCount
in interfaceTable
- 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 interfaceTable
- 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 interfaceTable
- 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 interfaceTable
- 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 interfaceTable
- 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 interfaceTable
- Returns:
- table end row index on sheet
- Since:
- 3.15 beta 2
-
getStyle
-
contains
Description copied from interface:Table
checks if the given cell is part of the table. Includes checking that they are on the same sheet. -
onTableDelete
protected void onTableDelete()Remove relations
-
getColumnCount()
instead.