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 voidcommit()Save the content in the underlying package part.booleancontains(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.intfindColumnIndex(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.intGet 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.CTTableget the underlying CTTable XML beanintGet the number of data rows in this table.intGet the bottom-right column index on the sheetintGet the bottom-right row indexintgetName()Get the name of the table.longDeprecated.intGet 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.intGet the top-left column index relative to the sheetintGet the top-left row index on the sheetgetStyle()intDeprecated.UseXSSFTableColumn.getXmlColumnPr()instead.booleanNote: This is misleading.booleanmapsTo(long id) Checks if this Table element contains even a single mapping to the map identified by idprotected voidRemove relationsvoidreadFrom(InputStream is) Read table XML from anInputStreamvoidremoveColumn(int columnIndex) Remove a column from the table.voidremoveColumn(XSSFTableColumn column) Remove a column from the table.voidsetArea(AreaReference tableArea) Set the area reference for the cells which this table covers.protected voidsetCellRef(AreaReference refs) voidSet the area reference for the cells which this table covers.voidsetDataRowCount(int newDataRowCount) Set the number of rows in the data area of the table.voidsetDisplayName(String name) Changes the display name of the TablevoidChanges the name of the TablevoidsetStyleName(String newStyleName) Changes the name of the TablevoidSynchronize table headers with cell values in the parent sheet.voidClears the cached values set bygetStartCellReference()andgetEndCellReference().voidwriteTo(OutputStream out) write table XML to anOutputStreamMethods 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:POIXMLDocumentPartSave 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:
commitin 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, ornullfor 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:TableGet the name of the table. -
setName
Changes the name of the Table- Parameters:
newName- The name of the table.
-
getStyleName
- Specified by:
getStyleNamein 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:
-
- "Open Office XML Part 4: chapter 3.5.1.2, attribute ref"
-
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:
-
- "Open Office XML Part 4: chapter 3.5.1.2, attribute ref"
-
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 isnullor not- Since:
- 4.0.0
-
getArea
Get the area that this table covers.- Returns:
- the table's area or
nullif 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) Returns0if 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. Returns0if 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-1ifcolumnis 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:
findColumnIndexin 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:TableReturns the sheet name that the table belongs to.- Specified by:
getSheetNamein 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:
isHasTotalsRowin 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:
getTotalsRowCountin 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:
getHeaderRowCountin 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:TableGet the top-left column index relative to the sheet- Specified by:
getStartColIndexin interfaceTable- Returns:
- table start column index on sheet
- Since:
- 3.15 beta 2
-
getStartRowIndex
public int getStartRowIndex()Description copied from interface:TableGet the top-left row index on the sheet- Specified by:
getStartRowIndexin interfaceTable- Returns:
- table start row index on sheet
- Since:
- 3.15 beta 2
-
getEndColIndex
public int getEndColIndex()Description copied from interface:TableGet the bottom-right column index on the sheet- Specified by:
getEndColIndexin interfaceTable- Returns:
- table end column index on sheet
- Since:
- 3.15 beta 2
-
getEndRowIndex
public int getEndRowIndex()Description copied from interface:TableGet the bottom-right row index- Specified by:
getEndRowIndexin interfaceTable- Returns:
- table end row index on sheet
- Since:
- 3.15 beta 2
-
getStyle
-
contains
Description copied from interface:Tablechecks 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.