org.formulacompiler.spreadsheet
Interface EngineBuilder

public interface EngineBuilder

Simplified interface to AFC's spreadsheet compiler functionality for the most typical use-cases. Typical example:

private RebateComputationFactory compileFactoryFromSpreadsheet( File _sheetFile ) throws Exception
{
  EngineBuilder builder = SpreadsheetCompiler.newEngineBuilder();
  builder.loadSpreadsheet( _sheetFile );
  builder.setFactoryClass( RebateComputationFactory.class );
  builder.bindAllByName();
  builder.failIfByNameBindingLeftNamedCellsUnbound();

  Engine engine = builder.compile();
  return (RebateComputationFactory) engine.getComputationFactory();
}

Please refer to the tutorial for details.

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

Author:

peo

getNumericType

NumericType getNumericType()

Returns the numeric type used by computations compiled by this builder.

setNumericType

void setNumericType(NumericType _type)

Sets the numeric type to be used by computations compiled by this builder.

See the tutorial for details.

getComputationMode

ComputationMode getComputationMode()

Returns the computation mode to be used for compiled engines. If this method returns null then a default computation mode for a spreadsheet source will be used.

Returns:

the computation mode if it was set or null otherwise.

setComputationMode

void setComputationMode(ComputationMode _computationMode)

Tells AFC to calculate expressions as for example Excel or OpenOffice does.

Parameters:

_computationMode - the computation mode to be used for compiled engines.

getSpreadsheet

Spreadsheet getSpreadsheet()

Gets the spreadsheet representation that this builder compiles. This is mostly useful after having called loadSpreadsheet(File).

setSpreadsheet

void setSpreadsheet(Spreadsheet _sheet)

Sets the spreadsheet representation that this builder compiles. You normally do this if you have loaded the spreadsheet using one of the loading methods of SpreadsheetCompiler, or after having constructed the spreadsheet in-memory using a SpreadsheetBuilder.

Parameters:

_sheet - is the spreadsheet representation to use as input for spreadsheet compilation.

See Also:

loadSpreadsheet(File)

loadSpreadsheet

void loadSpreadsheet(java.io.File _file)
                     throws java.io.FileNotFoundException,
                            java.io.IOException,
                            SpreadsheetException

Loads the input spreadsheet from a file.

Parameters:

_file - is the spreadsheet file to load.

Throws:

java.io.FileNotFoundException

java.io.IOException

SpreadsheetException

See Also:

setSpreadsheet(Spreadsheet), setLoadAllCellValues(boolean)

setLoadAllCellValues

void setLoadAllCellValues(boolean _value)

Controls whether Spreadsheet.Cell.getValue() should return valid values instead of null for computed cells. The default is false.

See Also:

loadSpreadsheet(File)

getInputClass

java.lang.Class getInputClass()

Returns the application-specific type defining the methods which input cells can call.

See Also:

setInputClass(Class)

setInputClass

void setInputClass(java.lang.Class _inputClass)

Sets the application-specific type defining the methods which input cells can call. Must be public. Can only be left null if a factory type is provided (see setFactoryClass(Class)), from which it is then inferred. If the factory method is provided, then this class must be assignable from the factory method's single argument.

See the tutorial for details.

See Also:

setFactoryMethod(Method)

getOutputClass

java.lang.Class getOutputClass()

Returns the application-specific type defining the methods which output cells can implement.

See Also:

setOutputClass(Class)

setOutputClass

void setOutputClass(java.lang.Class _outputClass)

Sets the application-specific type defining the methods output cells can implement. If a class, then the generated computation extends this class. If an interface, then the generated computation implements this interface. Must be public. Can only be left null if a factory type is provided (see setFactoryClass(Class)), from which it is then inferred. If the factory method is set, then the factory method's return type must be assignable from this class.

See the tutorial for details.

See Also:

setFactoryMethod(Method)

getFactoryClass

java.lang.Class getFactoryClass()

Returns the application-specific type to be used for the generated factory.

See Also:

setFactoryClass(Class)

setFactoryClass

void setFactoryClass(java.lang.Class _class)

Sets either an application-specific class from which to descend the generated computation factory, or an application-specific interface which the generated factory should implement. Must be public. Can be left null. If set, it must be public and have at most a single abstract method.

If you don't specify the factory method, setFactoryMethod(Method), then AFC infers it as the sole abstract method, or else the first overridable method of the type that has the proper application-specific computation factory signature.

See the tutorial for details.

getFactoryMethod

java.lang.reflect.Method getFactoryMethod()

Returns the application-specific factory method.

See Also:

setFactoryMethod(Method)

setFactoryMethod

void setFactoryMethod(java.lang.reflect.Method _factoryMethod)

Sets the application-specific method of the given factory type, setFactoryClass(Class), which AFC should implement to return new computation instances. Must be public and have a single parameter of the input type of the spreadsheet binding, and return the output type of the spreadsheet binding.

If you specify the factory type, then this must be a method of it. If not, then the factory type is taken to be the declaring type of this method.

If you don't specify the input and output types, then they are inferred from this factory method. If you do, then they must be compatible with the type of the single argument and the return type of this factory method, respectively. More precisely, the input type must be assignable from the type of the single argument, and the return type must be assignable from the output type.

See the tutorial for details.

getFullCaching

boolean getFullCaching()

Indicates whether AFC should compile the computation with full internal caching of values, or only (usually minimal) caching at its own discretion.

See Also:

setFullCaching(boolean)

setFullCaching

void setFullCaching(boolean _enabled)

Controls whether AFC should compile the computation with full internal caching of values, or only (usually minimal) caching at its own discretion.

See Also:

getFullCaching()

areAnyNamesDefined

boolean areAnyNamesDefined()

Checks whether the spreadsheet contains any named cells or ranges.

createCellNamesFromRowTitles

void createCellNamesFromRowTitles()

Uses a SpreadsheetNameCreator to create cell names from row titles in the first sheet of the spreadsheet. This method is called by bindAllByName() automatically if areAnyNamesDefined() returns false.

See the tutorial for details.

getRootBinder

SpreadsheetBinder.Section getRootBinder()
                                        throws CompilerException

Returns the root of the SpreadsheetBinder used by this engine builder to associate cells with Java methods. You only need to access it if neither the behaviour of bindAllByName(), nor that of the getByNameBinder() is sufficient for you.

Returns:

the root section binder.

Throws:

CompilerException

newCallFrame

CallFrame newCallFrame(java.lang.reflect.Method _method,
                       java.lang.Object... _args)

Constructs a call, possibly the initial call in a chain of calls.

Parameters:

_method - is the method to be called.

_args - is the list of arguments for the method's parameters.

See Also:

FormulaCompiler.newCallFrame(Method, Object...)

getByNameBinder

SpreadsheetByNameBinder getByNameBinder()
                                        throws CompilerException

Returns the SpreadsheetByNameBinder used by this engine builder to associate cells with Java methods. You only need to access it if the behaviour of bindAllByName() is not sufficient for you.

Returns:

the binder.

Throws:

CompilerException

bindAllByName

void bindAllByName()
                   throws CompilerException

Uses reflection to bind all named cells in the spreadsheet to corresponding methods on the input and output types. More precisely:

• Outputs and inputs are bound independently; the same cell can be bound to both (the output is then a direct passthrough to the corresponding input).
• Multiple cells can be bound to the same input method (cells "GETXY" and "XY" to xy()).
• Multiple output methods can be bound to the same cell (getXY() and xy() to cell "XY").
• In both cases, the exact name of the cell/method takes precedence.

See the tutorial for details.

Here's what this method does:

if (!areAnyNamesDefined()) {
  createCellNamesFromRowTitles();
}
SpreadsheetByNameBinder bn = getByNameBinder();
bn.outputs().bindAllMethodsToNamedCells();
bn.inputs().bindAllNamedCellsToMethods();

Throws:

CompilerException

See Also:

bindAllByName(String, String), failIfByNameBindingLeftNamedCellsUnbound()

bindAllByName

void bindAllByName(java.lang.String _inputPrefix,
                   java.lang.String _outputPrefix)
                   throws CompilerException

Uses reflection to bind all named cells in the spreadsheet to corresponding methods on the input and output types, provided the cell names have the specified prefixes.

See the tutorial for details.

Here's what this method does:

if (!areAnyNamesDefined()) {
  createCellNamesFromRowTitles();
}
SpreadsheetByNameBinder bn = getByNameBinder();
bn.outputs().bindAllMethodsToPrefixedNamedCells( _outputPrefix );
bn.inputs().bindAllPrefixedNamedCellsToMethods( _inputPrefix );

Parameters:

_inputPrefix - is what cell names used for input methods must start with.

_outputPrefix - is what cell names used for output methods must start with.

Throws:

CompilerException

See Also:

bindAllByName(), failIfByNameBindingLeftNamedCellsUnbound()

failIfByNameBindingLeftNamedCellsUnbound

void failIfByNameBindingLeftNamedCellsUnbound()
                                              throws CompilerException

Raises an exception if there are named cells that were not bound.

Throws:

SpreadsheetException.NameNotFound - if there is an unbound name.

CompilerException

See Also:

bindAllByName(), getByNameBinder()

failIfByNameBindingLeftNamedCellsUnbound

void failIfByNameBindingLeftNamedCellsUnbound(java.lang.String _inputPrefix,
                                              java.lang.String _outputPrefix)
                                              throws CompilerException

Raises an exception if there are named cells with one of the given prefixes that were not bound.

Parameters:

_inputPrefix - is what cell names used for input methods must start with.

_outputPrefix - is what cell names used for output methods must start with.

Throws:

SpreadsheetException.NameNotFound - if there is an unbound name.

CompilerException

See Also:

bindAllByName(), getByNameBinder()

getParentClassLoaderForEngine

java.lang.ClassLoader getParentClassLoaderForEngine()

Returns the parent class loader used for the compiled engine (which is itself class loader).

Returns:

ClassLoader.getSystemClassLoader() if the value was never modified, or else the value you have last set.

See Also:

setParentClassLoaderForEngine(ClassLoader), compile()

setParentClassLoaderForEngine

void setParentClassLoaderForEngine(java.lang.ClassLoader _value)

Sets the parent class loader to be used for the compiled engine (which is itself a class loader).

Parameters:

_value - is the new parent class loader. It probably never makes sense to pass null here.

See Also:

getParentClassLoaderForEngine(), compile()

getCompileTimeConfig

Computation.Config getCompileTimeConfig()

Let's you control the compile-time locale and timezone configuration by setting fields of the returned object.

Please refer to the tutorial for details.

Returns:

The current configuration. Never null.

See Also:

setCompileTimeConfig(Computation.Config)

setCompileTimeConfig

void setCompileTimeConfig(Computation.Config _value)

Let's you replace the entire compile-time configuration in one go.

Parameters:

_value - is the new configuration; must not be null.

See Also:

getCompileTimeConfig()

getCompileToReadableCode

boolean getCompileToReadableCode()

Controls whether AFC should attempt to compile more readable code (when decompiled), possibly at the expense of engine size and performance.

Returns:

true means make more readable, false means make more efficient (default).

setCompileToReadableCode

void setCompileToReadableCode(boolean _value)

Controls whether AFC should attempt to compile more readable code (when decompiled), possibly at the expense of engine size and performance.

Parameters:

_value - : true means make more readable, false means make more efficient (default).

getComputationListenerEnabled

boolean getComputationListenerEnabled()

Controls whether AFC should compile the computation with support for CellComputationListener.

Returns:

true if CellComputationListener will be supported. The default is false.

See Also:

CellComputationListener, Computation.Config.cellComputationListener

setComputationListenerEnabled

void setComputationListenerEnabled(boolean _enabled)

Controls whether AFC should compile the computation with support for CellComputationListener.

Parameters:

_enabled - if true then CellComputationListener will be supported. The default is false.

See Also:

CellComputationListener, Computation.Config.cellComputationListener

getConstantExpressionOptimizationListener

ConstantExpressionOptimizationListener getConstantExpressionOptimizationListener()

Returns a listener that receives notifications about events during compilation process, if any.

Returns:

compilation events listewner.

setConstantExpressionOptimizationListener

void setConstantExpressionOptimizationListener(ConstantExpressionOptimizationListener _listener)

Sets a listener that receives notifications about events during compilation process.

Parameters:

_listener - compilation events listewner.

compile

SaveableEngine compile()
                       throws CompilerException,
                              EngineException

Compiles an executable computation engine from the inputs to this builder. In particular, you must have loaded a spreadsheet, set the input and output types, or the factory type, and bound spreadsheet cells to methods.

See the tutorial for details.

Returns:

the compiled engine, ready to be used immediately, or saved to persistent storage for later use.

Throws:

CompilerException

EngineException

See Also:

loadSpreadsheet(File), setInputClass(Class), setOutputClass(Class), setFactoryClass(Class), setFullCaching(boolean), bindAllByName(), setParentClassLoaderForEngine(ClassLoader)