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

Nested Class Summary
static interface Spreadsheet.Cell
          Returns information about a spreadsheet cell.
static interface Spreadsheet.Range
          Marker interface for a spreadsheet range in the spreadsheet model.
static interface Spreadsheet.Row
          Returns information about a row.
static interface Spreadsheet.Sheet
          Returns information about a worksheet.
 
Method Summary
 void defineAdditionalRangeName(java.lang.String _name, Spreadsheet.Range _ref)
          Defines an additional range name to be returned by getRangeNames et al.
 Spreadsheet.Cell getCell(int _sheetIndex, int _columnIndex, int _rowIndex)
          Get a cell by its index.
 Spreadsheet.Cell getCell(java.lang.String _rangeName)
          Get a cell by its range name.
 Spreadsheet.Cell getCellA1(java.lang.String _a1Name)
          Get a cell by its A1-style name.
 Spreadsheet.Range getRange(java.lang.String _rangeName)
          Get a range by its name.
 java.util.Map<java.lang.String,Spreadsheet.Range> getRangeNames()
          Get all the range (and cell) names defined for this spreadsheet.
 Spreadsheet.Sheet[] getSheets()
          Returns the worksheets defined in the spreadsheet.
 
Methods inherited from interface org.formulacompiler.compiler.Describable
describe, toString
 

Method Detail

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.