5

Adding Formulas to JClass LiveTable

Introduction  com.klg.jclass.util.formulae's Hierarchy  Expressions and Results  Math Values

Operations  Exceptions  Using Formulae in JClass LiveTable

---

5.1 Introduction

The formulae package in com.klg.jclass.util has special capabilities for evaluating mathematical objects. Similar to the way that objects such as java.lang.Double wrap a primitive type, those in com.klg.jclass.util.formulae encapsulate mathematical expressions (operators) whose operands may be scalars, vectors (in the mathematical sense), and matrices. These objects may then be stored as the generalized values of cells in a JClass LiveTable, or in a JClass PageLayout table, where they may be evaluated at run time to produce results based on the then-current data.

In addition, subclasses of MathValue, which are wrappers for generalized scalars, vectors, and matrices, provide several methods for converting an expression to a value and to a String, as well as other methods useful when dealing with these objects.

---

5.2 com.klg.jclass.util.formulae's Hierarchy

The interfaces, abstract classes, and derived classes, including possible exception classes, are shown in Figure 13.

Figure 13 :  The inheritance hierarchy for com.klg.jclass.util.formulae.

The diverse set of mathematical operations permit you to compose complex mathematical formulas and provide references to them. Dynamic updating of the value represented by the expression is made possible through callbacks to the mathematical expression object.

---

5.3 Expressions and Results

The top-level interface for the com.klg.jclass.util.formulae package is Expression, whose sole method is evaluate(). Any object that functions as an expression must have an evaluate() method that knows how to operate on data that might be a scalar, a vector, or a matrix. Applying the evaluate() method to an Expression produces a Result, which is a marker interface that identifies Expression types that are valid return types from the evaluation of other Expressions.

An Expression may be an Operation, as in:

  Expression f = new Add(op1, op2);

which, after evaluation, returns a Result.

---

5.4 Math Values

The abstract class MathValue forms the root for all derived constant-based result/data classes. It satisfies the Expression interface by defining an evaluate() method, which simply returns the MathValue as a Result. Its concrete subclasses are MathMatrix, MathScalar, and MathVector. Because MathValue has an evaluate() method it is an Expression. Thus, MathValues may be passed as Expression objects.

MathValue Methods

MathValue Method	Description
evaluate()	Satisfies the Expression interface by returning the stored value. No evaluation is required because no operation is implied.
getDataFormat()	Retrieves the NumberFormat associated with this data.
matrixValue()	Gets the contents of this MathValue as a matrix of Numbers.
numberValue()	Gets the contents of this MathValue as a Number.
setDataFormat()	Sets a NumberFormat to use on the contents of this MathValue.
vectorValue()	Gets the contents of this MathValue as a vector of Numbers.

Note: The subclasses of MathValue override all but the first method. Since, for example, matrixValue() is not appropriate to a MathScalar, it throws an UnsupportedOperationException if it is called. Other method-data type mismatches also throw UnsupportedOperationExceptions. The method tables for the subclasses indicate which methods are data type mismatches for the given class.

5.4.1 MathScalar

MathScalar is a scalar constant represented as a MathValue. By encapsulating it in this fashion it can support integer and real numbers, and it can be extended if necessary to support other types of scalar numbers. Its data field is a realValue, a Number that is output based on the current dataFormat kept in MathValue.

Example:

  double s1 = 10.0; MathValue ss1 = new MathScalar(s1);

MathScalar Constructors

The no-argument constructor MathScalar() creates an instance that encapsulates the value 0.0, while the other three constructors take a double, an int, or a java.lang.Number argument.

MathScalar Methods

MathScalar Method	Description
matrixValue()	Throws an UnsupportedOperationException.
numberValue()	Gets the contents of this MathValue as a Number.
toString()	Returns a String representation of this value.
vectorValue()	Throws an UnsupportedOperationException.

5.4.2 MathVector

MathVector is a representation of the class of vectors in a linear algebra sense. They may also be used as operands in matrix multiplication. A MathVector encapsulates a list of values which may be integers, doubles, or more generally, objects of type Number. It has methods for retrieval or modification of a value at a particular index, and for outputting the list as a String. The operators discussed in the next section accept these objects as operands.

Example:

  double[] ed = {2.71828, 3.1415927, 1.6020505};
  MathValue mv = new MathVector(ed);

MathVector Constructors

The constructors for MathVector parallel those for MathScalar, except they take arrays as parameters rather than single values.

MathVector Methods

MathVector Method	Description
getValueAt()	Retrieves the value at a particular index in the vector.
matrixValue()	Throws an UnsupportedOperationException.
numberValue()	Throws an UnsupportedOperationException.
setValueAt()	Sets the value at a particular index in the vector.
toString()	Outputs the value of this vector as a String.
vectorValue()	Gets the contents of this MathValue as a vector of Numbers.

5.4.3 MathMatrix

MathMatrix is a representation of the class of matrices, again in the sense of linear algebra. The package implements the basic addition and multiplication operations in matrix algebra, including multiplying a matrix by a vector. It has methods for retrieval or modification of a value at a particular pair of indices, and for outputting the matrix as a String. The operators discussed in the next section accept these objects as operands.

Example:

  double[][] m1 = {{1.1, 1.2, 1.3},
           {2.1, 2.2, 2.3},
           {3.1, 3.2, 3.3}};
  MathValue mm = new MathMatrix(m1);

MathMatrix Constructors

The constructors for MathMatrix parallel those for MathScalar, except they take 2D arrays as parameters rather than single values.

MathMatrix Methods

MathMatrix Method	Description
getValueAt()	Retrieves the value at a particular row, column pair of index values in the matrix.
matrixValue()	Gets the contents of this MathValue as an array of Numbers.
numberValue()	Throws an UnsupportedOperationException.
setValueAt()	Sets the value at a particular row, column pair of index values in the matrix.
toString()	Outputs the value of this vector as a String.
vectorValue()	Throws an UnsupportedOperationException.

---

5.5 Operations

The abstract Operation class defines the basic elements of an operator. Binary operators have a left and right operand, which enables the correct ordering to be applied to matrix operations and any other non-commutative operators. Unary operators have a single operand.

Example:

    double[] ed = {2.71828, 3.1415927, 1.6020505};
    double[] rd = {(Math.sqrt(5.0) + 1.0) / 2.0, 4.0, 32.0};

    MathValue e = new MathVector(ed);
    MathValue r = new MathVector(rd);

    Expression add = new Add(e, r);

Operation Constructors

There is a no-argument constructor that creates a generic operator, and there are constructors for every unary and binary permutation of Expressions and Numbers. A sample constructor is: Operation(Expression left, Expression right).

Operation Methods

The two non-inherited methods in Operation are evaluate(), which returns a Result containing the evaluation of the expression, and clone(), which returns a deep-copy clone of the operation and of all operands.

5.5.1 The Defined Mathematical Operations

Unary Operators

Unary operators take one parameter, which is either an Expression or a Number. Because they are Expressions they all have an evaluate() method which returns a Result.

Operator	Description
Abs	The class for the absolute value operation. The operand may be a Number or an Expression, which may be a MathScalar or an ExpressionList, but not a vector or a matrix.
Ceiling	Ceiling is defined as the least integer greater than or equal to the operand, which may be a MathValue.
Floor	Floor is defined as the greatest integer less than or equal to the operand.
Root	Returns the positive square root of its operand.
Round	Round is defined as nearest integer to the operand. Rounding is done to an even number if the operand is exactly midway between two integers.
Trunc	Takes the integer part of a number. Equivalent to rounding to the nearest integer closer to zero. Example: trunc(-3.5) = -3.

Binary Operators

Binary operators take two parameters, which are Expressions, Numbers, or one of each. Because they are Expressions they all have an evaluate() method which returns a Result.

Operator	Description
Add	Adds two Expressions. If the Expressions are vectors of the same length, pairwise addition is performed. Matrices may be added providing the two operands have the same number of rows and columns. Unary addition is possible, and returns the evaluated operand.
Average	Average (arithmetic mean) is defined as the sum of all elements divided by the number of elements. Its one-parameter constructor is an Expression, usually a list. Its two-parameter constructors are combinations of Expressions and Numbers.
Count	Count determines the total number of elements in its operands. Its one- and two-parameter constructors take one or two Expressions (usually a list or lists) and count their elements.
Divide	Division is the ratio of two operands. The left operand is the numerator and the right operand is the denominator.
GeometricMean	Geometric mean is defined as the nth root of the product of a set of n numbers. Its one-parameter constructor takes an Expression, usually a list. Its two-parameter constructors take combinations of Expressions and Numbers, multiplying all elements together and taking the nth root.
Max	Max is defined for a pair of elements or across a list. It selects the largest element. Its one-parameter constructor takes an Expression, usually a list. Its two-parameter constructors take combinations of Expressions and Numbers, examining all elements and selecting the largest.
Median	The Median of a list is the middle element of a sorted list, or the average of the two middle values if the list has an even number of elements. Its one- and two-parameter constructors take one or two Expressions.
Min	Min is defined for a pair of elements or across a list. It selects the smallest element. Its one-parameter constructor takes an Expression, usually a list. Its two-parameter constructors take combinations of Expressions and Numbers, examining all elements and selecting the smallest.
Multiply	Multiplication is the product of a pair of elements. Its two-parameter constructors take combinations of Expressions and Numbers, examining all elements and selecting the smallest.
Power	The exponentiation (^) operation. Its two-parameter constructors take combinations of Expressions and Numbers. The left operand is the base and the right operand is the exponent.
Product	A product can be performed on a pair of elements or across a list. The product of an ExpressionList is the product of its individual members. Multiplication order is left-to-right, and first element of a list to last element. The result of a matrix multiplication may depend on the order of the operands.
Sort	This operation returns a sorted list of the given elements. Any secondary or nested lists are flattened.
StdDeviation	The sample standard deviation, given by sd = root( (sum(1 to n)(element - average)^2) / (n - 1)), where n is the number of samples and average is the sample average. It has one- and two-parameter constructors consisting of Expressions.
Subtract	The difference between two numbers. It has two-parameter constructors that take combinations of Expressions and Numbers.
Sum	A sum can be performed on a pair of elements or across a list. Its two-parameter constructors take combinations of Expressions and Numbers. Its one-parameter constructor usually takes an ExpressionList.

5.5.2 Reducing Operations to Values

Since Operations are Expressions, they all have an evaluate() method. Evaluation returns a Result, which may be converted to a String for printing. Here is an example:

  double edd = 2.0;
  double exp = 8.0;
  MathValue eddy = new MathScalar(edd);
  MathScalar expy = new MathScalar(exp);

  double[] ed = {2.71828, 3.1415927, 1.6020505};
  MathValue e = new MathVector(ed);

    Expression pow = new Power(eddy, expy);
    Expression powr = pow.evaluate();
    // Either one of these has a toString() method
    System.out.println("Power without evaluate(): " + pow);
    System.out.println("Power with evaluate(): " + powr);

After which the following is written on the output:

  Power without evaluate(): com.klg.jclass.util.formulae.Power@eb4f3b8c
  Power with evaluate(): 256.0

You see that calling evaluate() is necessary to have a value returned by the implicit toString() call.

---

5.6 Expression Lists

Expression lists are handy containers that permit you to perform an operation on a group of values.

MathExpressionList

The example shown here uses the binary form of Add to find the grand total of all the elements in two ExpressionLists.

  // Expression Lists
  Expression[] exprs1 = {null, null, null, null, null, null, null, null, null, null};
  for (int i = 0; i < 10; i++){
    exprs1[i] = new MathScalar(95 + i);
  }
  ExpressionList explist1 = new MathExpressionList(exprs1);

  Expression[] exprs2 = {null, null, null, null, null, null, null null, null, null};
  for (int i = 0; i < 10; i++){
    exprs2[i] = new MathScalar(95 + i);
  }
  ExpressionList explist2 = new MathExpressionList(exprs2);

  sss1 = new Sum(explist1, explist2);
  ssss1 = sss1.evaluate();
  System.out.println(
    "Summing ExpressionLists with evaluate(): " + ssss1);

Here's the output:

  Summing ExpressionLists with evaluate(): 1990

QueryExpressionList

A QueryExpressionList is designed as a wrapper for a set of Expressions stored in a JDBC-type ResultSet; that is, the result of a database query. Users of JClass DataSource may also use this facility.

TableExpressionList

Expression lists may be used to extend data from portions of a JClass LiveTable to produce summary reports. For details, see Section 5.9, Using Formulae in JClass LiveTable.

---

5.7 Events and Listeners

TableListenerPropagator

The TableListenerPropagator listener, which implements the JCTableDataListener interface, wraps a formula and listens for changes to table cells that are operands for this formula, and propagates the changes so that other interested listeners can re-evaluate themselves. The TableListenerPropagator listener automatically updates the whole dependency hierarchy of com.klg.jclass.util.formulae when a suboperation has been modified.

---

5.8 Exceptions

OperandMismatchException

Various operations such as adding a number to a vector are not defined, whereas other operations, for example, multiplying a vector by a number, can be interpreted as a scaling operation. At compile time, numbers, vectors, and matrices can be declared as generic Expressions, making it impossible to predetermine which operations are not permitted. A run time check of the validity of an operation must be made. If a mathematical construct is evaluated and found to be illegal, the class throws an OperandMismatchException.

ClassCastException

There are cases where a run time class cast exception may occur. While most of these should be avoidable by selecting the correct class (such as using Product rather than Multiply when multiplying two vectors) the fact that both take Expressions as their parameters makes it difficult to avoid the possibility of an end-user passing in an incorrect type if your application permits flexible user input. You may permit substitution of one arithmetic class for another, since they are all Operations. This also opens the door to class cast exceptions.

If the possibility exists for either of these exceptions, your code should attempt to handle it.

---

5.9 Using Formulae in JClass LiveTable

5.9.1 Registering a Cell Editor and a Cell Renderer with the JClass Central Registry

If you are planning to allow your end-users to specify mathematical operations, you may make use of the editor/renderer registry in com.klg.jclass.cell. Note that if a cell is placed in a JClass LiveTable, the ExpressionCellRenderer will be used by default.

The following code snippet, taken from the SpreadSheet demo, registers a cell editor that takes a value in the form of a util.formulae.Expression from a table cell and copies its String equivalent in a text box. In the SpreadSheet demo, formulas are entered by beginning them with an equal sign (=), for example, =SUM(A1:A5). The class called MyFormulaCellEditor recognizes this syntax and translates a String of this form to an Expression, then stores it in a table cell.

  EditorRendererRegistry.getCentralRegistry().addClass(
    "java.lang.String",
     null,
    "demos.table.spreadsheet.MyFormulaCellEditor",
    "com.klg.jclass.cell.renderers.JCStringCellRenderer");

See the SpreadSheet demo for a complete code listing.

5.9.2 Performing a Mathematical Operation on a Range of Cells

Expression Lists and Expression References

Expression list objects hold a group of Expressions. ExpressionList is an abstract class whose methods permit the inclusion of additional elements to those already present, a method for removing elements or clearing all elements, for retrieving an element, and for comparing with another list. These operations are common to the concrete classes MathExpressionList, QueryExpressionList, and TableExpressionList.

Expression lists may be used as arguments for all mathematical operations. When given an expression list, evaluating a unary operator such as ABS returns a list containing the absolute values of its input list. Binary operators may return a single result or a list. Given expression lists, the mathematical operators Abs, Add, Ceiling, Divide, Floor, Multiply, Power, Remainder, Root, Round, Sort, and Subtract return lists, while Average, Count, GeometricMean, Max, Median, Min, Product, and Sum all return a single result after evaluate() has been called.

Use TableExpressionList to perform an operation over a range of cells in a table. The following code snippet shows that the required parameters are a table data model and a block of cells.

  Expression expression = new TableExpressionList(
              table.getDataSource(),
              new MathScalar(startRow),      // first row
              new MathScalar(endRow),      // last row
              new MathScalar(startColumn),      // first column
              new MathScalar(endColumn)      // last column
              );
  Sum sum = new Sum(expression);

The next code fragment places the formula for the sum in the last column, just below the last row. With the proper cell renderer/editor combination, such as the one listed in the previous section, the formula or the numerical value of the sum is shown, depending on whether the cell is selected or not.

((EditableTableDataModel)table.getDataSource()).setTableDataItem(sum, endRow + 1, endColumn);

The advantage of using TableExpressionLists is that the formulas containing them know to update themselves when a cell's value is altered.