How to write formula functions - diirt/diirt GitHub Wiki

The simplest way to learn how to write a formula function is to look at the implementation of the ones already provided in the formula package.

Each package (e.g. array, math, vnumber, ...) provides a set of functions. Each function can be implemented as an inner class, a package private class or a public class. The function set must be a registered extension using the ServiceLoader pattern. The pom.xml shows how.

Types of functions

The first step is to determine which kind of function you are implementing and choose the appropriate class to implement. Choose between these options, and refers to the examples and javadocs for more details.

• FormulaFunction - This is the base interface for all formula functions. This should be used for all pure functions (i.e. stateless, the result is only determined by the arguments). For examples, see EnumFromVNumberFunction, ConcatStringsFunction (uses var args), ConditionalOperatorFormulaFunction.

• AbstractXxxToXxxFormulaFunction - These classes can be extended for pure functions that match the argument types and return types. They take care of details such as null values, alarms and timestamp. For examples, see MathFunctionSet, VNumberFunctionSet.

• StatefulFormulaFunction - This is the base class for all stateful functions, those where the return value is not determined just by the arguments. For examples, see HistogramOfFormulaFunction, CFQueryFunction.

• DynamicFormulaFunction - This is the base class for all functions that may dynamically connect and disconnect channels. For examples, see ChannelFormulaFunction, CaHistogramFormulaFunction.

When implementing a function, you should keep in mind null values, alarm conditions, timestamp, metadata and, in case of stateful functions, cleanup.