org.formulacompiler.spreadsheet
Interface Spreadsheet

All Superinterfaces:

Describable

public interface Spreadsheet
extends Describable

Represents a spreadsheet model in memory. It can be constructed from different spreadsheet file formats, for example Excel .xls and .xml, and OpenOffice Calc (see SpreadsheetCompiler.loadSpreadsheet(java.io.File)). It serves as input to the SpreadsheetToEngineCompiler implementations and thus decouples engine compilation from the different spreadsheet file formats supported by AFC.

The spreadsheet model is immutable except for one thing. As a convenience, you can add custom range names to be used by getCell(String), getRange(String), and getRangeNames(). These are never used internally to resolve formula references and do not affect the semantics of the spreadsheet model. We support this convenience so that code already written against the getCell(String) API can transparently profit from names extracted from a spreadsheet's layout, for instance.

The handling of additional range names is not thread-safe.

This interface is an API only. Do not implement it yourself.

Author:

peo

See Also:

SpreadsheetLoader, SpreadsheetBuilder, SpreadsheetToEngineCompiler

getCell

Spreadsheet.Cell getCell(int _sheetIndex,
                         int _columnIndex,
                         int _rowIndex)

Get a cell by its index.

Parameters:

_sheetIndex - is 0-based index of the sheet in the workbook (typically 0).

_columnIndex - is the 0-based column index of the cell (so 0 is A, 1 is B, etc.).

_rowIndex - is the 0-based row index of the cell.

Returns:

The requested cell, or possibly null if the cell is not defined in the spreadsheet.

getCell

Spreadsheet.Cell getCell(java.lang.String _rangeName)
                         throws SpreadsheetException.NameNotFound,
                                java.lang.IllegalArgumentException

Get a cell by its range name.

Parameters:

_rangeName - is the name of a single-cell range (BasePrice, NumberSold, etc.). Range names are case-insensitive.

Returns:

The requested cell. The returned reference may specify a cell that is not within the actual bounds of the spreadsheet. In this case, it denotes an empty cell.

Throws:

SpreadsheetException.NameNotFound - if the name is not defined in the spreadsheet.

java.lang.IllegalArgumentException - if the name identifies a range instead of a single cell.

See Also:

getRange(String)

getCellA1

Spreadsheet.Cell getCellA1(java.lang.String _a1Name)
                           throws SpreadsheetException.NameNotFound

Get a cell by its A1-style name. Sheet references are not supported.

Parameters:

_a1Name - is the cell's A1-style name (A1, B5, AA15, etc.).

Returns:

The requested cell. The returned reference may specify a cell that is not within the actual bounds of the spreadsheet. In this case, it denotes an empty cell.

Throws:

SpreadsheetException.NameNotFound - if the name is not parseable as an A1-style cell reference.

getRange

Spreadsheet.Range getRange(java.lang.String _rangeName)
                           throws SpreadsheetException.NameNotFound,
                                  java.lang.IllegalArgumentException

Get a range by its name.

Parameters:

_rangeName - is a name in getRangeNames() (Items, Employees, etc.). Range names are case-insensitive.

Returns:

The requested range. Might be a single cell.

Throws:

SpreadsheetException.NameNotFound - if the name is not defined in the spreadsheet.

java.lang.IllegalArgumentException - if the name identifies a range instead of a single cell.

See Also:

getRangeNames(), getCell(String)

getRangeNames

java.util.Map<java.lang.String,Spreadsheet.Range> getRangeNames()

Get all the range (and cell) names defined for this spreadsheet. The key of the map is the range's specific name defined in the spreadsheet (Items, Employees, etc.). The value of the map is the named range or cell.

This map is initialized from the range names defined in the loaded spreadsheet (or constructed using a SpreadsheetBuilder). It can be extended using defineAdditionalRangeName(String, Range).

Returns:

The read-only map of case-insensitive names to corresponding ranges.

See Also:

defineAdditionalRangeName(String, Range), getRange(String), getCell(String)

defineAdditionalRangeName

void defineAdditionalRangeName(java.lang.String _name,
                               Spreadsheet.Range _ref)
                               throws java.lang.IllegalArgumentException

Defines an additional range name to be returned by getRangeNames et al. Such additional names are never used internally to resolve formula references and do not affect the semantics of the spreadsheet model.

We support this convenience method so that code written against the getCell(String) API can transparently profit from additional names extracted, for instance, from a spreadsheet's layout.

Parameters:

_name - is the name to be defined. It must not collide with a range name defined by the underlying spreadsheet model (as loaded from a file or constructed by a builder). Range names are case-insensitive.

_ref - is the range or single cell to be named.

Throws:

java.lang.IllegalArgumentException - if either argument is null, or if the name collides with a model-defined name.

getSheets

Spreadsheet.Sheet[] getSheets()

Returns the worksheets defined in the spreadsheet.