Tutorial

This is the tutorial for the Abacus Formula Compiler (AFC). It is organized as a collection of examples and reference topics, which are best read in the order presented here. You might also want to have a look at the Function Reference and the API Reference.

Fundamentals

To demonstrate why AFC was built, I introduce a simple example: an order entry application where the line item rebate is made customizable. The shortcomings of this solution are overcome in the topic below, which introduces AFC.

AFC normally does all numeric calculations using the double type. This is often not acceptable for financial applications. This topic shows how to make an engine use one of the precise types BigDecimal and scaled long for all numeric computations.

There are a few spreadsheet functions that need to take a user’s locale and time zone into account. While the default is to use the current settings, server-side applications might want to override them.

Many computations can be sped up by turning on internal caching of cell values. And some functions (NOW and MATCH, for example), or repeating sections, always use internal caches. Caches, however, introduce state. You need to reset this state when reusing computations on modified inputs.

To go one step further, sometimes you need AFC to compute distinct output values for each of the elements of a variable-length data series. For example, the bonus amount for each employee, given the total bonus for the company. Doing the loop over the series yourself can be severely limiting the range of computations your users can formulate because they cannot aggregate over the whole series. AFC therefore supports per-element outputs in repeating sections.

Binding in Detail

Advanced use cases concerning the binding of the input and output cells of a spreadsheet to the methods of your Java interfaces or classes.

Miscellany

If you want to know what kind of code AFC generates, looking at the resulting JVM byte code is not everyone’s thing. To simplify this, you can ask AFC to decompile the generated byte code to Java source code (this feature uses the JODE library).

Some applications may wish to use AFC to compile computation engines, but want users to be able to specify simple computations without having to setup a spreadsheet file. These can use a builder to dynamically construct a spreadsheet model as input to AFC.

Allows you to generate initial spreadsheet files that, for instance, already define cells for the most typically used inputs and outputs. Or, when you are using AFC without a spreadsheet file, you can let users switch to using one transparently by generating a file for their existing formula definition.

Some companies use a custom ClassLoader to, for example, speed up class loading. If you don’t replace Java’s default class loader (ClassLoader.getSystemClassLoader()), you may have to make sure that the engines generated by AFC use your custom implementation.

See what happens when something goes wrong, and find hints on what to do.

Note On The Sample Code

To ensure its correctness, all the sample code in this tutorial has been cited from automated tests that are run with every release build (unless stated otherwise). The tests and data can be found in in the source distribution of AFC in