1package io.protobase.f7.formulas;
 2
 3import io.protobase.f7.errors.ValueException;
 4import io.protobase.f7.models.GridColumnRowKey;
 5
 6/**
 7 * All formulas are similar to the functional interface, accepting any number of Objects and returning a single Object,
 8 * which could be a list containing many more objects.
 9 * <p>
10 * In order to keep these formulas simple, clean, and concise, we have two methods, one calling the other, but catching
11 * F7 errors/exceptions and returning them as objects. See {@link AbstractFormula} for more info.
12 * <p>
13 * All formulas accept a variable number of Object arguments, and return an Object. While in Java-Land this means we
14 * could accept anything that extends an Object, in practice we only use the following types:
15 * Boolean - Wraps primitive, can be converted to Double or String without error.
16 * Double - Can be converted to Boolean, String without error.
17 * String - Can be converted to Boolean, Double, but may throw {@link ValueException}.
18 * List\Object - Depending on contents, may be able to be converted to other types.
19 * <p>
20 * WARNING: These are the only types that Formulas should work with, and convert to/from. Even if an Object that can be
21 * easily cast to one of these is passed in, there's no guarantee that it will be cast, and will probably result in
22 * error.
23 */
24public interface Formula {
25  FormulaName NAME = null;
26
27  /**
28   * Primary method that will execute this formula with the provided args.
29   *
30   * @param origin - origin key of the cell that is running this formula. Can be null.
31   * @param args   - variables to use in this formula's execution.
32   * @return error or result.
33   */
34  Object apply(GridColumnRowKey origin, Object... args);
35
36  /**
37   * Where the main logic of the formula should reside. Will attempt to execute the formula logic, but may throw a
38   * F7Exception.
39   *
40   * @param args - variables to use in this formula's execution.
41   * @return error or result.
42   */
43  Object internal(GridColumnRowKey origin, Object... args);
44}