Top Description Constructors Methods
org.apache.poi.ss.usermodel

public abstract Class CellBase

extends Object
implements Cell
Class Inheritance
All Implemented Interfaces
org.apache.poi.ss.usermodel.Cell
Known Direct Subclasses
org.apache.poi.hssf.usermodel.HSSFCell
Imports
org.apache.poi.ss.SpreadsheetVersion, org.apache.poi.ss.formula.FormulaParseException, org.apache.poi.ss.util.CellAddress, .CellRangeAddress, .CellReference, java.time.LocalDateTime, java.util.Calendar, .Date, .Locale
Common implementation-independent logic shared by all implementations of Cell.

Constructor Summary

AccessConstructor and Description
public
CellBase()

Method Summary

Modifier and TypeMethod and Description
private void
checkLength(String value)

public CellAddress
getAddress()

Implements org.apache.poi.ss.usermodel.Cell.getAddress.

Gets the address of this cell

protected abstract SpreadsheetVersion

Returns:

the spreadsheet version
getSpreadsheetVersion()

Get the spreadsheet version for the given implementation.

protected final CellType

Returns:

value type
getValueType()

Get value type of this cell.

public final void
removeFormula()

Implements org.apache.poi.ss.usermodel.Cell.removeFormula.

Removes formula, if any.

protected abstract void
removeFormulaImpl()

Implementation-specific removal of the formula.

public void
setBlank()

Implements org.apache.poi.ss.usermodel.Cell.setBlank.

Removes formula and value from the cell, and sets its type to CellType#BLANK.

public final void
setCellFormula(String
the formula to set, e.g. "SUM(C4:E4)". If the argument is null then the current formula is removed.
formula)

Implements org.apache.poi.ss.usermodel.Cell.setCellFormula.

Sets formula for this cell.

protected abstract void
setCellFormulaImpl(String
The text of the formula to set.
formula)

Implementation-specific setting the formula.

public final void
setCellType(CellType cellType)

Implements org.apache.poi.ss.usermodel.Cell.setCellType.

Set the cells type (blank, numeric, boolean, error or string).

protected abstract void
setCellTypeImpl(CellType
new cell type. Guaranteed non-null, not _NONE.
cellType)

Implementation-specific logic

public void
setCellValue(double
the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numeric cell and set its value.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a numeric value for the cell.

public void
setCellValue(Date
the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numerics cell and set its value.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

public void
setCellValue(LocalDateTime
the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numerics cell and set its value.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

public void
setCellValue(Calendar
the date value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numeric cell and set its value.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a date value for the cell.

public void
setCellValue(String
value to set the cell to. For formulas, we'll set the formula string, for String cells we'll set its value. For other types, we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a string value for the cell.

public void
setCellValue(RichTextString
value to set the cell to. For formulas, we'll set the formula string, for String cells we'll set its value. For other types, we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.
value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a rich string value for the cell.

protected abstract void
setCellValueImpl(double
the new value to set
value)

Implementation-specific way to set a numeric value.

protected abstract void
setCellValueImpl(Date
the new date to set
value)

Implementation-specific way to set a date value.

protected abstract void
setCellValueImpl(LocalDateTime
the new date to set
value)

Implementation-specific way to set a date value.

protected abstract void
setCellValueImpl(Calendar
the new calendar value to set
value)

Implementation-specific way to set a calendar value.

protected abstract void
setCellValueImpl(String
the new value to set.
value)

Implementation-specific way to set a string value.

protected abstract void
setCellValueImpl(RichTextString
the new value to set.
value)

Implementation-specific way to set a RichTextString value.

public final void
tryToDeleteArrayFormula(String
a customized exception message for the case if deletion of the cell is impossible. If null, a default message will be generated
message)

Called when this an array formula in this cell is deleted.

private void
tryToDeleteArrayFormulaIfSet()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

CellBaseback to summary
public CellBase()

Method Detail

checkLengthback to summary
private void checkLength(String value)
getAddressback to summary
public CellAddress getAddress()

Implements org.apache.poi.ss.usermodel.Cell.getAddress.

Doc from org.apache.poi.ss.usermodel.Cell.getAddress.

Gets the address of this cell

Returns:CellAddress

A1 style address of this cell

Annotations
@Override
getSpreadsheetVersionback to summary
protected abstract SpreadsheetVersion getSpreadsheetVersion()

Get the spreadsheet version for the given implementation.

Returns:SpreadsheetVersion

the spreadsheet version

getValueTypeback to summary
protected final CellType getValueType()

Get value type of this cell. Can return BLANK, NUMERIC, STRING, BOOLEAN or ERROR. For current implementations where type is strongly coupled with formula, is equivalent to getCellType() == CellType.FORMULA ? getCachedFormulaResultType() : getCellType()

This is meant as a temporary helper method until the time when value type is decoupled from the formula.

Returns:CellType

value type

removeFormulaback to summary
public final void removeFormula()

Implements org.apache.poi.ss.usermodel.Cell.removeFormula.

Doc from org.apache.poi.ss.usermodel.Cell.removeFormula.

Removes formula, if any. If cell was blank, leaves it as is. If it is a part of an array formula group, blanks the cell. If has a regular formula, removes the formula preserving the "cached" value.

Annotations
@Override
removeFormulaImplback to summary
protected abstract void removeFormulaImpl()

Implementation-specific removal of the formula. The cell is guaranteed to have a regular formula set. Shall preserve the "cached" value.

setBlankback to summary
public void setBlank()

Implements org.apache.poi.ss.usermodel.Cell.setBlank.

Doc from org.apache.poi.ss.usermodel.Cell.setBlank.

Removes formula and value from the cell, and sets its type to CellType#BLANK. Preserves comments and hyperlinks. While setCellType(CellType) exists, is an alias for setCellType(CellType.BLANK).

Annotations
@Override
setCellFormulaback to summary
public final void setCellFormula(String formula) throws FormulaParseException, IllegalStateException

Implements org.apache.poi.ss.usermodel.Cell.setCellFormula.

Doc from org.apache.poi.ss.usermodel.Cell.setCellFormula.

Sets formula for this cell.

If formula is not null, sets or updates the formula. If formula is null, removes the formula. Or use removeFormula() to remove the formula.

Note, this method only sets the formula string and does not calculate the formula value. To set the precalculated value use setCellValue.

If the cell was blank, sets value to 0. Otherwise, preserves the value as precalculated.

In XSSF implementation, there is a XSSFWorkbook.setCellFormulaValidation(boolean) setting that can validate (but also in some cases, reformat) the formula.

Parameters
formula:String

the formula to set, e.g. "SUM(C4:E4)". If the argument is null then the current formula is removed.

Annotations
@Override
Exceptions
FormulaParseException:
if the formula has incorrect syntax or is otherwise invalid
IllegalStateException:
if this cell is a part of an array formula group containing other cells
setCellFormulaImplback to summary
protected abstract void setCellFormulaImpl(String formula)

Implementation-specific setting the formula. Formula is not null. Shall not change the value.

Parameters
formula:String

The text of the formula to set.

setCellTypeback to summary
public final void setCellType(CellType cellType)

Implements org.apache.poi.ss.usermodel.Cell.setCellType.

Doc from org.apache.poi.ss.usermodel.Cell.setCellType.

Set the cells type (blank, numeric, boolean, error or string).

If the cell currently contains a value, the value will be converted to match the new type, if possible. Formatting is generally lost in the process however.

Conversion rules:

to NUMERIC: numeric value is left as is. True converts to 1.0, false converts to 0. otherwise, the value is set to 0. Formula is removed.

If what you want to do is get a String value for your numeric cell, stop! This is not the way to do it. Instead, for fetching the string value of a numeric or boolean or date cell, use DataFormatter instead.

If cell is a member of an array formula group containing more than 1 cell, an IllegalStateException is thrown. If the array formula group contains only this cell, it is removed.

Passing CellType#FORMULA is illegal and will result in an IllegalArgumentException.

Annotations
@Override
setCellTypeImplback to summary
protected abstract void setCellTypeImpl(CellType cellType)

Implementation-specific logic

Parameters
cellType:CellType

new cell type. Guaranteed non-null, not _NONE.

setCellValueback to summary
public void setCellValue(double value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a numeric value for the cell.

Parameters
value:double

the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numeric cell and set its value.

Annotations
@Override
setCellValueback to summary
public void setCellValue(Date value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

Note

- There is actually no 'DATE' cell type in Excel. In many cases (when entering date values), Excel automatically adjusts the cell style to some date format, creating the illusion that the cell data type is now something besides CellType#NUMERIC. POI does not attempt to replicate this behaviour. To make a numeric cell display as a date, use setCellStyle(CellStyle) etc.

Parameters
value:Date

the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numerics cell and set its value.

Annotations
@Override
setCellValueback to summary
public void setCellValue(LocalDateTime value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

Note

- There is actually no 'DATE' cell type in Excel. In many cases (when entering date values), Excel automatically adjusts the cell style to some date format, creating the illusion that the cell data type is now something besides CellType#NUMERIC. POI does not attempt to replicate this behaviour. To make a numeric cell display as a date, use setCellStyle(CellStyle) etc.

Parameters
value:LocalDateTime

the numeric value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numerics cell and set its value.

Annotations
@Override
setCellValueback to summary
public void setCellValue(Calendar value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as a date.

This will set the cell value based on the Calendar's timezone. As Excel does not support timezones this means that both 20:00+03:00 and 20:00-03:00 will be reported as the same value (20:00) even that there are 6 hours difference between the two times. This difference can be preserved by using setCellValue(value.getTime()) which will automatically shift the times to the default timezone.

Parameters
value:Calendar

the date value to set this cell to. For formulas, we'll set the precalculated value, for numerics we'll set its value. For other types, we will change the cell to a numeric cell and set its value.

Annotations
@Override
setCellValueback to summary
public void setCellValue(String value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a string value for the cell.

Parameters
value:String

value to set the cell to. For formulas, we'll set the formula string, for String cells we'll set its value. For other types, we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.

Annotations
@Override
setCellValueback to summary
public void setCellValue(RichTextString value)

Implements org.apache.poi.ss.usermodel.Cell.setCellValue.

Doc from org.apache.poi.ss.usermodel.Cell.setCellValue.

Set a rich string value for the cell.

Parameters
value:RichTextString

value to set the cell to. For formulas, we'll set the formula string, for String cells we'll set its value. For other types, we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.

Annotations
@Override
setCellValueImplback to summary
protected abstract void setCellValueImpl(double value)

Implementation-specific way to set a numeric value. value is guaranteed to be a valid (non-NaN) double. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return CellType#NUMERIC.

Parameters
value:double

the new value to set

setCellValueImplback to summary
protected abstract void setCellValueImpl(Date value)

Implementation-specific way to set a date value. value is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return CellType#NUMERIC.

Parameters
value:Date

the new date to set

setCellValueImplback to summary
protected abstract void setCellValueImpl(LocalDateTime value)

Implementation-specific way to set a date value. value is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return CellType#NUMERIC.

Parameters
value:LocalDateTime

the new date to set

setCellValueImplback to summary
protected abstract void setCellValueImpl(Calendar value)

Implementation-specific way to set a calendar value. value is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return CellType#NUMERIC.

Parameters
value:Calendar

the new calendar value to set

setCellValueImplback to summary
protected abstract void setCellValueImpl(String value)

Implementation-specific way to set a string value. The value is guaranteed to be non-null and to satisfy the length limitation imposed by the spreadsheet version. The implementation is expected to adjust cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() (whichever appropriate) would return CellType#STRING.

Parameters
value:String

the new value to set.

setCellValueImplback to summary
protected abstract void setCellValueImpl(RichTextString value)

Implementation-specific way to set a RichTextString value. The value is guaranteed to be non-null, having non-null value, and to satisfy the length limitation imposed by the spreadsheet version. The implementation is expected to adjust cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() (whichever appropriate) would return CellType#STRING.

Parameters
value:RichTextString

the new value to set.

tryToDeleteArrayFormulaback to summary
public final void tryToDeleteArrayFormula(String message)

Called when this an array formula in this cell is deleted.

The purpose of this method is to validate the cell state prior to modification.

Parameters
message:String

a customized exception message for the case if deletion of the cell is impossible. If null, a default message will be generated

Exceptions
IllegalStateException:
if modification is not allowed Note. Exposing this to public is ugly. Needed for methods like Sheet#shiftRows.
See Also
setCellType(CellType), setCellFormula(String), Row#removeCell(org.apache.poi.ss.usermodel.Cell), org.apache.poi.ss.usermodel.Sheet#removeRow(org.apache.poi.ss.usermodel.Row), org.apache.poi.ss.usermodel.Sheet#shiftRows(int, int, int), org.apache.poi.ss.usermodel.Sheet#addMergedRegion(org.apache.poi.ss.util.CellRangeAddress)
tryToDeleteArrayFormulaIfSetback to summary
private void tryToDeleteArrayFormulaIfSet()