nl.fountain.xelem.excel
Interface Workbook

All Superinterfaces:

XLElement

All Known Implementing Classes:

XLWorkbook

public interface Workbook
extends XLElement

Represents the Workbook element, the root of a SpreadsheetML document.

Creating SpreadsheetML and Excel workbooks from within Java starts here. Besides adding child XLElements and setting other features, the Workbook can be used to merge Styles. After finishing the Workbook you'll probably want to create the Document, the structure that holds this Workbook and all of it's children. This is done with the createDocument()-method.

A Workbook might also be obtained from an ExcelReader, an object that reads Excel xml-files or xml-InputSources.

See Also:

overview

Field Summary

Fields inherited from interface nl.fountain.xelem.excel.XLElement

PREFIX_HTML, PREFIX_O, PREFIX_SS, PREFIX_X, XMLNS, XMLNS_HTML, XMLNS_O, XMLNS_SS, XMLNS_X

Method Summary

NamedRange	addNamedRange(NamedRange namedRange) Adds a new NamedRange to this workbook.
NamedRange	addNamedRange(String name, String refersTo) Adds a new NamedRange to this workbook.
Worksheet	addSheet() Adds a new Worksheet to this workbook.
Worksheet	addSheet(String name) Adds a new Worksheet to this workbook with the given name as name.
Worksheet	addSheet(Worksheet sheet) Adds the given Worksheet to this workbook.
void	appendInfoSheet() Appends a Worksheet with general information to this Workbook.
Document	createDocument() Creates a Document, the structure that holds this Workbook and all of it's children.
DocumentProperties	getDocumentProperties() Gets the DocumentProperties of this workbook.
ExcelWorkbook	getExcelWorkbook() Gets the ExcelWorkbook of this workbook.
String	getFileName() Gets the filename of this Workbook.
String	getName() Gets the name of this Workbook.
Map<String,NamedRange>	getNamedRanges() Gets all the NamedRanges that were added to this workbook.
List<String>	getSheetNames() Gets a list of all the names of worksheets in this workbook in display order.
List<String>	getWarnings() Gets a list of warnings (Strings) that were registered during assembly of this workbook after a call to createDocument().
Worksheet	getWorksheet(String name) Gets the worksheet with the given name.
Worksheet	getWorksheetAt(int index) Gets the worksheet at the given index.
List<Worksheet>	getWorksheets() Gets a list of all the worksheets in this workbook in display order.
boolean	hasDocumentProperties() Specifies whether this workbook has DocumentProperties.
boolean	hasExcelWorkbook() Specifies whether this workbook has an ExcelWorkbook.
boolean	isPrintingDocComments() Specifies whether this Workbook's createDocument()-method will include docComments.
boolean	isPrintingElementComments() Specifies whether this Workbook's createDocument()-method will include comments.
void	mergeStyles(String newID, String id1, String id2) Merges two SpreadsheetML Style elements.
Worksheet	removeSheet(String name) Removes the sheet with the given name.
void	setDocumentProperties(DocumentProperties docProps) Set the DocumentProperties of this workbook or, if this workbook allready had DocumentProperties, replace it.
void	setExcelWorkbook(ExcelWorkbook excelWb) Set the ExcelWorkbook of this workbook or, if this workbook allready had an ExcelWorkbook, replace it.
void	setFileName(String filename) Sets the filename of this Workbook.
void	setName(String name) Sets the name of this Workbook.
void	setPrintDocComments(boolean print) Sets whether this Workbook's createDocument()-method will include docComments.
void	setPrintElementComments(boolean print) Sets whether this Workbook's createDocument()-method will print comments which were set with XLElement.addElementComment(String).

Methods inherited from interface nl.fountain.xelem.excel.XLElement

addElementComment, assemble, getElementComments, getNameSpace, getPrefix, getTagName, setAttributes, setChildElement

Method Detail

setName

void setName(String name)

Sets the name of this Workbook.

getName

String getName()

Gets the name of this Workbook.

setFileName

void setFileName(String filename)

Sets the filename of this Workbook.

getFileName

String getFileName()

Gets the filename of this Workbook. If no filename was supplied with setFileName(String) the name of the workbook is returned with the extension '.xls'.

mergeStyles

void mergeStyles(String newID,
                 String id1,
                 String id2)
                 throws UnsupportedStyleException

Merges two SpreadsheetML Style elements.

Parameters:

newID - the ss:ID of the new merged style

id1 - the ss:ID of the copied style

id2 - the ss:ID of the appended style

Throws:

UnsupportedStyleException - if either of the styles mentioned with id1 or id2 are unknown to the factory.

See Also:

XFactory.mergeStyles(String, String, String)

setPrintElementComments

void setPrintElementComments(boolean print)

Sets whether this Workbook's createDocument()-method will print comments which were set with XLElement.addElementComment(String).

The default is true.

See Also:

XLElement.addElementComment(String)

isPrintingElementComments

boolean isPrintingElementComments()

Specifies whether this Workbook's createDocument()-method will include comments.

setPrintDocComments

void setPrintDocComments(boolean print)

Sets whether this Workbook's createDocument()-method will include docComments. DocComments are the comments that will be passed in at the start of the Workbook document, just after the processing instruction.

DocComments can be configured in the configuration file, standard at config/xelem.xml.

The default is true.

See Also:

XFactory.getDocComments()

isPrintingDocComments

boolean isPrintingDocComments()

Specifies whether this Workbook's createDocument()-method will include docComments.

appendInfoSheet

void appendInfoSheet()

Appends a Worksheet with general information to this Workbook. The infoSheet is allways displayed as the last worksheet.

setDocumentProperties

void setDocumentProperties(DocumentProperties docProps)

Set the DocumentProperties of this workbook or, if this workbook allready had DocumentProperties, replace it.

Parameters:

docProps - the DocumentProperties for this workbook

getDocumentProperties

DocumentProperties getDocumentProperties()

Gets the DocumentProperties of this workbook.

Returns:

The DocumentProperties of this workbook. Never null.

hasDocumentProperties

boolean hasDocumentProperties()

Specifies whether this workbook has DocumentProperties.

setExcelWorkbook

void setExcelWorkbook(ExcelWorkbook excelWb)

Set the ExcelWorkbook of this workbook or, if this workbook allready had an ExcelWorkbook, replace it.

Parameters:

excelWb - The ExcelWorkbook for this workbook

getExcelWorkbook

ExcelWorkbook getExcelWorkbook()

Gets the ExcelWorkbook of this workbook.

Returns:

The ExcelWorkbook of this workbook. Never null.

hasExcelWorkbook

boolean hasExcelWorkbook()

Specifies whether this workbook has an ExcelWorkbook.

addNamedRange

NamedRange addNamedRange(String name,
                         String refersTo)

Adds a new NamedRange to this workbook. Named ranges are usefull when working with formulas.

The string refersTo should be of format [worksheet name]!R1C1:R1C1. If this workbook allready contained a NamedRange with the given name, replaces it.

Parameters:

name - The name to apply to the range.

refersTo - A String of R1C1 reference style, including worksheet name.

Returns:

New NamedRange.

addNamedRange

NamedRange addNamedRange(NamedRange namedRange)

Adds a new NamedRange to this workbook. If this workbook allready contained a NamedRange with an equal name, replaces it.

Parameters:

namedRange - the NamedRange to be added to this workbook

Returns:

the given NamedRange

getNamedRanges

Map<String,NamedRange> getNamedRanges()

Gets all the NamedRanges that were added to this workbook. The map-keys are equal to their names.

Returns:

a map with NamedRanges

addSheet

Worksheet addSheet()

Adds a new Worksheet to this workbook. The new sheet will have the name "Sheet[x]", where [x] is a sequential number to prevent the duplication of sheet names. The worksheets cellpointer will be at position row 1, column 1.

Returns:

A new Worksheet.

addSheet

Worksheet addSheet(String name)

Adds a new Worksheet to this workbook with the given name as name. The worksheets cellpointer will be at position row 1, column 1.

Parameters:

name - The name that is to be given to the new worksheet.

Returns:

A new Worksheet.

Throws:

DuplicateNameException - if a sheet with this name is allready present in this workbook.

addSheet

Worksheet addSheet(Worksheet sheet)

Adds the given Worksheet to this workbook.

Parameters:

sheet - The worksheet to be added.

Returns:

The passed Worksheet.

Throws:

DuplicateNameException - if a sheet with such a name is allready present in this workbook.

removeSheet

Worksheet removeSheet(String name)

Removes the sheet with the given name.

Parameters:

name - The name of the worksheet to remove.

Returns:

The removed worksheet or null if a worksheet with the given name was not in this workbook.

getWorksheets

List<Worksheet> getWorksheets()

Gets a list of all the worksheets in this workbook in display order.

Returns:

A list of worksheets.

getSheetNames

List<String> getSheetNames()

Gets a list of all the names of worksheets in this workbook in display order. This list may be used to manipulate the display order of sheets. For instance:

              Collections.swap(workbook.getSheetNames(), 0, 2);

will display the first worksheet added to this workbook at position 3.

No objects should be added to this list.

Returns:

A list of sheet names.

getWorksheet

Worksheet getWorksheet(String name)

Gets the worksheet with the given name.

Parameters:

name - The name of the worksheet.

Returns:

The worksheet with the given name or null if no worksheet with that name was in this workbook.

getWorksheetAt

Worksheet getWorksheetAt(int index)

Gets the worksheet at the given index. The worksheet index is 0-based.

Parameters:

index - the worksheet index number

Returns:

the worksheet at the given index or null if no worksheet was at that index

createDocument

Document createDocument()
                        throws ParserConfigurationException

Creates a Document, the structure that holds this Workbook and all of it's children.

During assembly non fatal-errors will be registered as warnings. See getWarnings(). A new call to createDocument erases all previous warnings.

Non fatal-errors could be:

• The XFactory could not be configured.
• There was no definition for a 'Default' style in the XFactory. The workbook will create a standard 'Default' style.
• A cell, column, row or table was given a styleID, but the corresponding definition of that style was not found in the XFactory. The workbook will create an empty definition of that style (i.e. <Style ss:ID="foo"/>).
• The method appendInfoSheet() was called, but an infoSheet-Node could not be created.

Returns:

A Document, representing this workbook.

Throws:

ParserConfigurationException - if the document could not be created.

getWarnings

List<String> getWarnings()

Gets a list of warnings (Strings) that were registered during assembly of this workbook after a call to createDocument().

Returns:

A list of warnings. The list may be empty if no warnings were generated.