Package net.sf.jett.transform

Class ExcelTransformer

java.lang.Object

net.sf.jett.transform.ExcelTransformer

public class ExcelTransformer
extends java.lang.Object

The ExcelTransformer class represents the main JETT API.

An ExcelTransformer knows how to transform Excel template workbooks into fully populated Excel workbooks, using caller-supplied data in the form of beans. This class is the entry point API for JETT.

There are six entry-point methods that accomplish all of the work, all with the overloaded name "transform". The first 3 apply all bean values to all sheets. The third method does the work; the preceding 2 each call it to perform the actual transformation. The last 3 apply specific sets of bean values to specific sheets. The last method does the work; the preceding 2 each call it to perform the actual transformation.

• public void transform(String inFilename, String outFilename, Map<String, Object> beans) throws IOException, InvalidFormatException
• public Workbook transform(InputStream is, Map<String, Object> beans) throws IOException, InvalidFormatException
• public void transform(Workbook workbook, Map<String, Object> beans)
• public void transform(String inFilename, String outFilename, List<String> templateSheetNamesList, List<String> newSheetNamesList, List<Map<String, Object>> beansList) throws IOException, InvalidFormatException
• public Workbook transform(InputStream is, List<String> templateSheetNamesList, List<String> newSheetNamesList, List<Map<String, Object>> beansList) throws IOException, InvalidFormatException
• public void transform(Workbook workbook, List<String> templateSheetNamesList, List<String> newSheetNamesList, List<Map<String, Object>> beansList)

The first method reads the template spreadsheet from the input filename, transforms the spreadsheet by calling the third method, and writes the transformed spreadsheet to the output filename.

The second method reads the template spreadsheet from the given input stream (usually a file), transforms the spreadsheet by calling the third method, and returns a Workbook object representing the transformed spreadsheet, which can be written to a file if desired.

The third method performs the actual transformation on a Workbook, applying bean values to all sheets.

The fourth method reads the template spreadsheet from the input filename, transforms the spreadsheet by calling the sixth method, and writes the transformed spreadsheet to the output filename.

The fifth method reads the template spreadsheet from the given input stream (usually a file), transforms the spreadsheet by calling the sixth method, and returns a Workbook object representing the transformed spreadsheet, which can be written to a file if desired.

The sixth method performs the actual transformation on a Workbook, applying specific bean values to specific sheets.

The ExcelTransformer's settings can be changed with the other public methods of this class, including recognizing custom tag libraries, adding CellListeners, using fixed size collections, turning off implicit collections processing, passing silent and lenient flags through to the underlying JEXL Engine, passing a cache size to the internal JEXL Engine, passing namespace objects to register custom functions in the JEXL Engine, and passing CSS files/text to be recognized by the StyleTag later.

Author:

Randy Gettman

Constructor Summary

Constructors

Constructor	Description
ExcelTransformer()	Construct an ExcelTransformer.

Method Summary

Modifier and Type	Method	Description
void	addCellListener(CellListener listener)	Registers the given CellListener.
void	addCssFile(java.lang.String filename)	Register a file containing CSS-like style definitions.
void	addCssText(java.lang.String cssText)	Register one or more style definitions, without having to read them from a file.
void	addFixedSizeCollectionName(java.lang.String collName)	This particular named Collection has a known size and does not need to have other Cells shifted out of the way for its contents; space is already allocated.
void	addSheetListener(SheetListener listener)	Registers the given SheetListener.
WorkbookContext	createContext(org.apache.poi.ss.usermodel.Workbook workbook, SheetTransformer transformer)	Creates a WorkbookContext for a Workbook.
WorkbookContext	createContext(org.apache.poi.ss.usermodel.Workbook workbook, SheetTransformer transformer, java.util.List<java.lang.String> templateSheetNames, java.util.List<java.lang.String> sheetNames, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansMaps)	Creates a WorkbookContext for a Workbook.
void	registerFuncs(java.lang.String namespace, java.lang.Object funcsObject)	Registers an object under the given namespace in the internal JEXL Engine.
void	registerTagLibrary(java.lang.String namespace, TagLibrary library)	Registers the given TagLibrary so that this ExcelTransformer can recognize tags from the given namespace.
void	setCache(int size)	Creates and uses a JEXL Expression cache of the given size.
void	setDebug(boolean debug)	Sets whether the JEXL "debug" flag is set.
void	setEvaluateFormulas(boolean evaluate)	After transformation, this determines whether JETT will evaluate all formulas and store their results in the Workbook.
void	setForceRecalculationOnOpening(boolean forceRecalc)	After transformation, if this was called, then JETT will set whether to force recalculation of formulas when Excel opens this workbook.
void	setLenient(boolean lenient)	Sets whether the JEXL "lenient" flag is set.
void	setSilent(boolean silent)	Sets whether the JEXL "silent" flag is set.
org.apache.poi.ss.usermodel.Workbook	transform(java.io.InputStream is, java.util.List<java.lang.String> templateSheetNamesList, java.util.List<java.lang.String> newSheetNamesList, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)	Transforms the template Excel spreadsheet represented by the given InputStream.
org.apache.poi.ss.usermodel.Workbook	transform(java.io.InputStream is, java.util.Map<java.lang.String,java.lang.Object> beans)	Transforms the template Excel spreadsheet represented by the given InputStream.
void	transform(java.lang.String inFilename, java.lang.String outFilename, java.util.List<java.lang.String> templateSheetNamesList, java.util.List<java.lang.String> newSheetNamesList, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)	Transforms the template Excel spreadsheet represented by the given input filename.
void	transform(java.lang.String inFilename, java.lang.String outFilename, java.util.Map<java.lang.String,java.lang.Object> beans)	Transforms the template Excel spreadsheet represented by the given input filename.
void	transform(org.apache.poi.ss.usermodel.Workbook workbook, java.util.List<java.lang.String> templateSheetNamesList, java.util.List<java.lang.String> newSheetNamesList, java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)	Transforms the template Excel spreadsheet represented by the given Workbook.
void	transform(org.apache.poi.ss.usermodel.Workbook workbook, java.util.Map<java.lang.String,java.lang.Object> beans)	Transforms the template Excel spreadsheet represented by the given Workbook.
void	turnOffImplicitCollectionProcessing(java.lang.String collName)	The caller is stating that it will be explicitly accessing item(s) in the named Collection, so implicit collections processing should NOT be performed on this collection.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExcelTransformer

public ExcelTransformer()

Construct an ExcelTransformer.

Method Detail

registerTagLibrary

public void registerTagLibrary(java.lang.String namespace,
                               TagLibrary library)

Registers the given TagLibrary so that this ExcelTransformer can recognize tags from the given namespace.

Parameters:

namespace - The namespace associated with the tag library.

library - The TagLibrary.

Throws:

java.lang.IllegalArgumentException - If the namespace has already been registered.

addCellListener

public void addCellListener(CellListener listener)

Registers the given CellListener.

Parameters:

listener - A CellListener.

addSheetListener

public void addSheetListener(SheetListener listener)

Registers the given SheetListener.

Parameters:

listener - A SheetListener.

Since:

0.8.0

addFixedSizeCollectionName

public void addFixedSizeCollectionName(java.lang.String collName)

This particular named Collection has a known size and does not need to have other Cells shifted out of the way for its contents; space is already allocated.

Parameters:

collName - The name of the Collection that doesn't need other Cells shifted out of the way for its contents.

turnOffImplicitCollectionProcessing

public void turnOffImplicitCollectionProcessing(java.lang.String collName)

The caller is stating that it will be explicitly accessing item(s) in the named Collection, so implicit collections processing should NOT be performed on this collection. Implicit collections processing will still occur on Collections known by other names.

Parameters:

collName - The name of the Collection on which NOT to perform implicit collections processing.

setLenient

public void setLenient(boolean lenient)

Sets whether the JEXL "lenient" flag is set.

Parameters:

lenient - Whether the JEXL "lenient" flag is set.

setSilent

public void setSilent(boolean silent)

Sets whether the JEXL "silent" flag is set. Default is false.

Parameters:

silent - Whether the JEXL "silent" flag is set.

setCache

public void setCache(int size)

Creates and uses a JEXL Expression cache of the given size. The given value is passed through to the JEXL Engine. The JEXL Engine establishes a parse cache; it's not a result cache.

Parameters:

size - The size of the JEXL Expression cache.

Since:

0.2.0

setDebug

public void setDebug(boolean debug)

Sets whether the JEXL "debug" flag is set. Default is false.

Parameters:

debug - Whether the JEXL "debug" flag is set.

Since:

0.9.1

registerFuncs

public void registerFuncs(java.lang.String namespace,
                          java.lang.Object funcsObject)

Registers an object under the given namespace in the internal JEXL Engine. Each public method in the object's class is exposed as a "function" available in the JEXL Engine. To use instance methods, pass an instance of the object. To use class methods, pass a Class object.

Parameters:

namespace - The namespace used to access the functions object.

funcsObject - An object (or a Class) containing the methods to expose as JEXL Engine functions.

Throws:

java.lang.IllegalArgumentException - If the namespace has already been registered.

Since:

0.2.0

addCssText

public void addCssText(java.lang.String cssText)

Register one or more style definitions, without having to read them from a file. Style definitions are of the format (whitespace is ignored):

[.styleName { [propertyName: value [; propertyName: value]* }]*

These style names are recognized by the "class" attribute of the "style" tag.

Parameters:

cssText - A string containing one or more style definitions.

Throws:

StyleParseException - If there is a problem parsing the style definition text.

Since:

0.5.0

See Also:

StyleTag

addCssFile

public void addCssFile(java.lang.String filename)
                throws java.io.IOException

Register a file containing CSS-like style definitions. Style definitions are of the format (whitespace is ignored):

[.styleName { [propertyName: value [; propertyName: value]* }]*

These style names are recognized by the "class" attribute of the "style" tag.

Parameters:

filename - The name of a file containing CSS-like style definitions.

Throws:

java.io.IOException - If there is a problem reading the file.

StyleParseException - If there is a problem parsing the style definition text.

Since:

0.5.0

See Also:

StyleTag

setEvaluateFormulas

public void setEvaluateFormulas(boolean evaluate)

After transformation, this determines whether JETT will evaluate all formulas and store their results in the Workbook. This defaults to false. If this is not set, then other tools may or may not evaluate the formulas in the workbook. If this is set, then the results will be stored, assuming that all formulas evaluated are supported by the underlying Apache POI library.

Parameters:

evaluate - Whether to have JETT evaluate all formulas and store their results.

Since:

0.8.0

setForceRecalculationOnOpening

public void setForceRecalculationOnOpening(boolean forceRecalc)

After transformation, if this was called, then JETT will set whether to force recalculation of formulas when Excel opens this workbook. If this is not called, then JETT will not change any value that may be present already in the workbook. This will not control whether JETT will attempt to evaluate all formulas; it will set or clear a flag that controls whether Excel will recalculate all formulas when it opens the workbook.

Parameters:

forceRecalc - The flag for Excel to determine whether to recalculate all formulas when opening the workbook.

Since:

0.8.0

transform

public void transform(java.lang.String inFilename,
                      java.lang.String outFilename,
                      java.util.Map<java.lang.String,java.lang.Object> beans)
               throws java.io.IOException,
                      org.apache.poi.openxml4j.exceptions.InvalidFormatException

Transforms the template Excel spreadsheet represented by the given input filename. Applies the given Map of beans to all sheets. Writes the resultant Excel spreadsheet to the given output filename.

Parameters:

inFilename - The template spreadsheet filename.

outFilename - The resultant spreadsheet filename.

beans - The Map of bean names to bean objects.

Throws:

java.io.IOException - If there is a problem reading or writing any Excel spreadsheet.

org.apache.poi.openxml4j.exceptions.InvalidFormatException - If there is a problem creating a Workbook object.

Since:

0.2.0

transform

public org.apache.poi.ss.usermodel.Workbook transform(java.io.InputStream is,
                                                      java.util.Map<java.lang.String,java.lang.Object> beans)
                                               throws java.io.IOException,
                                                      org.apache.poi.openxml4j.exceptions.InvalidFormatException

Transforms the template Excel spreadsheet represented by the given InputStream. Applies the given Map of beans to all sheets.

Parameters:

is - The InputStream from the template spreadsheet.

beans - The Map of bean names to bean objects.

Returns:

A new Workbook object capable of being written to an OutputStream.

Throws:

java.io.IOException - If there is a problem reading the template Excel spreadsheet.

org.apache.poi.openxml4j.exceptions.InvalidFormatException - If there is a problem creating a Workbook object.

transform

public void transform(org.apache.poi.ss.usermodel.Workbook workbook,
                      java.util.Map<java.lang.String,java.lang.Object> beans)

Transforms the template Excel spreadsheet represented by the given Workbook. Applies the given Map of beans to all sheets.

Parameters:

workbook - A Workbook object. Transformation is performed directly on this object.

beans - The Map of bean names to bean objects.

Since:

0.6.0

transform

public void transform(java.lang.String inFilename,
                      java.lang.String outFilename,
                      java.util.List<java.lang.String> templateSheetNamesList,
                      java.util.List<java.lang.String> newSheetNamesList,
                      java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)
               throws java.io.IOException,
                      org.apache.poi.openxml4j.exceptions.InvalidFormatException

Transforms the template Excel spreadsheet represented by the given input filename. If a sheet name is represented n times in the list of template sheet names, then it will cloned to make n total copies and the clones will receive the corresponding sheet name from the list of sheet names. Each resulting sheet has a corresponding Map of bean names to bean values exposed to it. Writes the resultant Excel spreadsheet to the given output filename.

Parameters:

inFilename - The template spreadsheet filename.

outFilename - The resultant spreadsheet filename.

templateSheetNamesList - A List of template sheet names, with duplicates indicating to clone sheets.

newSheetNamesList - A List of resulting sheet names corresponding to the template sheet names list.

beansList - A List of Maps representing the beans map exposed to each resulting sheet.

Throws:

java.io.IOException - If there is a problem reading or writing any Excel spreadsheet.

org.apache.poi.openxml4j.exceptions.InvalidFormatException - If there is a problem creating a Workbook object.

Since:

0.2.0

transform

public org.apache.poi.ss.usermodel.Workbook transform(java.io.InputStream is,
                                                      java.util.List<java.lang.String> templateSheetNamesList,
                                                      java.util.List<java.lang.String> newSheetNamesList,
                                                      java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)
                                               throws java.io.IOException,
                                                      org.apache.poi.openxml4j.exceptions.InvalidFormatException

Transforms the template Excel spreadsheet represented by the given InputStream. If a sheet name is represented n times in the list of template sheet names, then it will cloned to make n total copies and the clones will receive the corresponding sheet name from the list of sheet names. Each resulting sheet has a corresponding Map of bean names to bean values exposed to it.

Parameters:

is - The InputStream from the template spreadsheet.

templateSheetNamesList - A List of template sheet names, with duplicates indicating to clone sheets.

newSheetNamesList - A List of resulting sheet names corresponding to the template sheet names list.

beansList - A List of Maps representing the beans map exposed to each resulting sheet.

Returns:

A new Workbook object capable of being written to an OutputStream.

Throws:

java.io.IOException - If there is a problem reading the template Excel spreadsheet.

org.apache.poi.openxml4j.exceptions.InvalidFormatException - If there is a problem creating a Workbook object.

transform

public void transform(org.apache.poi.ss.usermodel.Workbook workbook,
                      java.util.List<java.lang.String> templateSheetNamesList,
                      java.util.List<java.lang.String> newSheetNamesList,
                      java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansList)

Transforms the template Excel spreadsheet represented by the given Workbook. If a sheet name is represented n times in the list of template sheet names, then it will cloned to make n total copies and the clones will receive the corresponding sheet name from the list of sheet names. Each resulting sheet has a corresponding Map of bean names to bean values exposed to it.

Parameters:

workbook - A Workbook object. Transformation is performed directly on this object.

templateSheetNamesList - A List of template sheet names, with duplicates indicating to clone sheets.

newSheetNamesList - A List of resulting sheet names corresponding to the template sheet names list.

beansList - A List of Maps representing the beans map exposed to each resulting sheet.

Since:

0.6.0

createContext

public WorkbookContext createContext(org.apache.poi.ss.usermodel.Workbook workbook,
                                     SheetTransformer transformer)

Creates a WorkbookContext for a Workbook.

Parameters:

workbook - The Workbook.

transformer - A SheetTransformer.

Returns:

A WorkbookContext.

createContext

public WorkbookContext createContext(org.apache.poi.ss.usermodel.Workbook workbook,
                                     SheetTransformer transformer,
                                     java.util.List<java.lang.String> templateSheetNames,
                                     java.util.List<java.lang.String> sheetNames,
                                     java.util.List<java.util.Map<java.lang.String,java.lang.Object>> beansMaps)

Creates a WorkbookContext for a Workbook.

Parameters:

workbook - The Workbook.

transformer - A SheetTransformer.

templateSheetNames - A List of template sheet names, from the transform method.

sheetNames - A List of sheet names, from the transform method.

beansMaps - A List of beans maps, from the transform method.

Returns:

A WorkbookContext.

Since:

0.8.0