org.apache.poi.ss.usermodel

Class CellBase

java.lang.Object

org.apache.poi.ss.usermodel.CellBase

All Implemented Interfaces:

Cell

Direct Known Subclasses:

HSSFCell, SXSSFCell, XSSFCell

public abstract class CellBase
extends java.lang.Object
implements Cell

Common implementation-independent logic shared by all implementations of Cell.

Author:

Vladislav "gallon" Galas gallon at apache dot org

Constructor Summary

Constructors

Constructor and Description
CellBase()

Method Summary

Modifier and Type	Method and Description
CellAddress	getAddress() Gets the address of this cell
protected abstract SpreadsheetVersion	getSpreadsheetVersion() Get the spreadsheet version for the given implementation.
protected CellType	getValueType() Get value type of this cell.
void	removeFormula() Removes formula, if any.
protected abstract void	removeFormulaImpl() Implementation-specific removal of the formula.
void	setBlank() Removes formula and value from the cell, and sets its type to CellType.BLANK.
void	setCellFormula(java.lang.String formula) Sets formula for this cell.
protected abstract void	setCellFormulaImpl(java.lang.String formula) Implementation-specific setting the formula.
void	setCellType(CellType cellType) Set the cells type (blank, numeric, boolean, error or string).
protected abstract void	setCellTypeImpl(CellType cellType) Implementation-specific logic
void	setCellValue(java.util.Calendar value) Set a date value for the cell.
void	setCellValue(java.util.Date value) Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.
void	setCellValue(double value) Set a numeric value for the cell.
void	setCellValue(java.time.LocalDateTime value) Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.
void	setCellValue(RichTextString value) Set a rich string value for the cell.
void	setCellValue(java.lang.String value) Set a string value for the cell.
protected abstract void	setCellValueImpl(java.util.Calendar value) Implementation-specific way to set a calendar value.
protected abstract void	setCellValueImpl(java.util.Date value) Implementation-specific way to set a date value.
protected abstract void	setCellValueImpl(double value) Implementation-specific way to set a numeric value.
protected abstract void	setCellValueImpl(java.time.LocalDateTime value) Implementation-specific way to set a date value.
protected abstract void	setCellValueImpl(RichTextString value) Implementation-specific way to set a RichTextString value.
protected abstract void	setCellValueImpl(java.lang.String value) Implementation-specific way to set a string value.
void	tryToDeleteArrayFormula(java.lang.String message) Called when this an array formula in this cell is deleted.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.poi.ss.usermodel.Cell

getArrayFormulaRange, getBooleanCellValue, getCachedFormulaResultType, getCellComment, getCellFormula, getCellStyle, getCellType, getColumnIndex, getDateCellValue, getErrorCellValue, getHyperlink, getLocalDateTimeCellValue, getNumericCellValue, getRichStringCellValue, getRow, getRowIndex, getSheet, getStringCellValue, isPartOfArrayFormulaGroup, removeCellComment, removeHyperlink, setAsActiveCell, setCellComment, setCellErrorValue, setCellStyle, setCellValue, setCellValue, setHyperlink

Constructor Detail

CellBase

public CellBase()

Method Detail

setCellType

public final void setCellType(CellType cellType)

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.

Specified by:

setCellType in interface Cell

setBlank

public void setBlank()

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

Specified by:

setBlank in interface Cell

getAddress

public CellAddress getAddress()

Gets the address of this cell

Specified by:

getAddress in interface Cell

Returns:

A1 style address of this cell

setCellTypeImpl

protected abstract void setCellTypeImpl(CellType cellType)

Implementation-specific logic

Parameters:

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

tryToDeleteArrayFormula

public final void tryToDeleteArrayFormula(java.lang.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 - a customized exception message for the case if deletion of the cell is impossible. If null, a default message will be generated

Throws:

java.lang.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), Sheet.removeRow(org.apache.poi.ss.usermodel.Row), Sheet.shiftRows(int, int, int), Sheet.addMergedRegion(org.apache.poi.ss.util.CellRangeAddress)

setCellFormula

public final void setCellFormula(java.lang.String formula)
                          throws FormulaParseException,
                                 java.lang.IllegalStateException

Sets formula for this cell.

If formula is not null, sets or updates the formula. If formula is null, removes the formula. Or use Cell.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 Cell.setCellValue(double).

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

Specified by:

setCellFormula in interface Cell

Parameters:

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

Throws:

FormulaParseException - if the formula has incorrect syntax or is otherwise invalid

java.lang.IllegalStateException - if this cell is a part of an array formula group containing other cells

See Also:

Cell.removeFormula()

setCellFormulaImpl

protected abstract void setCellFormulaImpl(java.lang.String formula)

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

Parameters:

formula -

getValueType

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:

value type

removeFormula

public final void 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.

Specified by:

removeFormula in interface Cell

removeFormulaImpl

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.

setCellValue

public void setCellValue(double value)

Set a numeric value for the cell.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValueImpl

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 - the new value to set

setCellValue

public void setCellValue(java.util.Date value)

Description copied from interface: Cell

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 Cell.setCellStyle(CellStyle) etc.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValue

public void setCellValue(java.time.LocalDateTime value)

Description copied from interface: Cell

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 Cell.setCellStyle(CellStyle) etc.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValueImpl

protected abstract void setCellValueImpl(java.util.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 - the new date to set

setCellValueImpl

protected abstract void setCellValueImpl(java.time.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 - the new date to set

setCellValue

public void setCellValue(java.util.Calendar value)

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.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValueImpl

protected abstract void setCellValueImpl(java.util.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 - the new calendar value to set

setCellValue

public void setCellValue(java.lang.String value)

Set a string value for the cell.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValueImpl

protected abstract void setCellValueImpl(java.lang.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 - the new value to set.

setCellValue

public void setCellValue(RichTextString value)

Set a rich string value for the cell.

Specified by:

setCellValue in interface Cell

Parameters:

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

setCellValueImpl

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 - the new value to set.

getSpreadsheetVersion

protected abstract SpreadsheetVersion getSpreadsheetVersion()

Get the spreadsheet version for the given implementation.

Returns:

the spreadsheet version