com.accountingenhancements.formula
Class FormulaFunction

java.lang.Object
  com.accountingenhancements.formula.FormulaFunction

Direct Known Subclasses:

FormulaFunction_DateAdd, FormulaFunction_DatePart, FormulaFunction_IIF, FormulaFunction_LCase, FormulaFunction_Left, FormulaFunction_Len, FormulaFunction_Mid, FormulaFunction_Right, FormulaFunction_UCase

public class FormulaFunction
extends java.lang.Object

A template for defined function. This class isn't used directly, all formula functions should extend this class.
For examples of how to define a function see FormulaFunction_Mid and FormulaFunction_IIF.
The usual constructor used is the FormulaFunction(FormulaVariable functionVariable) where functionVariable is a FormulaVariable of type TYPE_FUNCTION.
The (String) and (String, int) and (FormulaVariable) constructors use parseCommaDelimitedFunctionFields(String, int) to create the argument stack.
Arguments are handed to these functions as the contents of a stack. The stack can be created through the use of the static parseCommaDelimitedFunctionFields method.

The following is a convenient cut-and-paste for the base code for creating function code. Replace all code following your package statement with the following code. Perform a global replace on FormulaFunction_ with FormulaFunction_YourNewClassName then fix the FormulaFunction_YourNewClassNameYourNewClassName.java in the comment line at the top of this file.


import com.accountingenhancements.common.SupportParameters;
import com.accountingenhancements.formula.*;
import java.text.ParseException;
import java.util.HashMap;

/**
*
*
*@author ????
*/

public class FormulaFunction_ extends FormulaFunction{


/**
*Create a new FormulaFunction with an already defined functionArgumentStack.
*@param functionArgumentStack a list of FormulaVariables that are needed by the function.
*/
public FormulaFunction_(FormulaVariableStack functionArgumentStack){
super(functionArgumentStack);
}

/**
*Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function
*@param functionArgumentString the string representing the functions arguments. The outer parentheses must be removed.
*Example: If the function is IIF(A *@throws ParseException if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)
*/
public FormulaFunction_(String functionArgumentString) throws ParseException{
super(functionArgumentString);
}

/**
*Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function
*@param functionArgumentString the string representing the functions arguments. The outer parentheses must be removed.
*Example: If the function is IIF(A *@param level the level applied to the creation of FormulaVariables for the arguments.
*@throws ParseException if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)
*/
public FormulaFunction_(String functionArgumentString, int level) throws ParseException{
super(functionArgumentString,level);
}

/**
*Create a new FormulaFunction from the functionVariable (A FormulaVariable of TYPE_FUNCTION).
*This is the most common constructor used.
*@param functionVariable a FormulaVariable of TYPE_FUNCTION
*@throws ParseException if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)
*/
public FormulaFunction_(FormulaVariable functionVariable) throws ParseException{
super(functionVariable);
}

/**
*@return the name of this function
*/
public static String getName(){
return "";
}

/**
*@return String[][] of needed arguments and their dataTypes which as {{"Test Argument ARG1","TYPE_BOOLEAN"},{"True Argument ARG2","TYPE_?"},{"False Argument ARG3","TYPE_?"}}
*If handing this routine a FormulaVariableStack functionArgumentStack then the FormulaVariable arguments should be named, ARG1, ARG2, etc...
*/
public static String[][] getRequiredArguments(){
String[][] result={};
return result;
}
/**
*@return String[] description of return value and it's data type. {"Upper case result","TYPE_STRING"}
*/
public static String[] getReturnValueDescription(){
String[] result={};
return result;
}
/**
*Portion of code that actually solves the function.
*/
protected FormulaVariable solve(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) throws java.text.ParseException, java.lang.ArithmeticException, ClassNotFoundException{
FormulaVariable solution=null;
String resultString="";
int highestLevelUsed=0;
boolean treatUnquotedTextAsFormula=true;
FormulaVariable Arg_1=null;
Arg_1=functionArgumentStack.get("ARG1");
if(Arg_1==null)throw new java.lang.ArithmeticException("ARG1 is missing from functionArgumentStack");
Arg_1=Arg_1.solve(variableList,iteration,supportParameters,functionList,resolveEverythingAboveLevel);
if(Arg_1==null||Arg_1.isNull()==true||Arg_1.getString().length()==0)throw new java.lang.ArithmeticException("ARG1 is invalid");
if(highestLevelUsed < Arg_1.getHighestLevel())highestLevelUsed=Arg_1.getHighestLevel();



solution=new FormulaVariable("",resultString,highestLevelUsed,treatUnquotedTextAsFormula);
return solution;
}

}

Field Summary

protected FormulaVariableStack

functionArgumentStack The stack containing the function's arguments.

Constructor Summary

FormulaFunction(FormulaVariable functionVariable)
Create a new FormulaFunction from the functionVariable (A FormulaVariable of TYPE_FUNCTION).
This is the most common constructor used.

FormulaFunction(FormulaVariableStack functionArgumentStack)
Create a new FormulaFunction with an already defined functionArgumentStack.

FormulaFunction(java.lang.String functionArgumentString)
Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function

FormulaFunction(java.lang.String functionArgumentString, int level)
Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function

Method Summary

FormulaVariable	function(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) Programmer defined function.
FormulaVariable	function(FormulaVariableStack functionArgumentStack, FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) Programmer defined function. This function replaces the funcionArgumentStack and calls function(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) so you can leave this function alone, but the other function needs to be overriden.
FormulaVariableStack	getFunctionArgumentStack()
protected static FormulaVariableStack	getFunctionArgumentStackFromFunctionVariable(FormulaVariable functionVariable)
static java.lang.String	getName()
static java.lang.String[][]	getRequiredArguments()
static java.lang.String[][]	getRequiredFormulaVariables()
static java.lang.String[][]	getRequiredSupportParameters()
static java.lang.String[]	getReturnValueDescription()
protected static FormulaVariableStack	parseCommaDelimitedFunctionFields(java.lang.String formulaSegment, int level) Break the contents of a formula that are between parentheses into their constituent fields. Note: Examples are as seen in code, so "\\\"how\\\"" creates the string \"how\" and Hello\\, creates the string Hello\, Ex: "IIF(A formulaSegment = "A returnArray.get(0) == "A returnArray.get(1) == "\"Hello there, \\\"how\\\" are you\"" returnArray.get(2) == "1.34" Escaping a comma will cause the comma to be ignored. Ex: "Hello\\, how are you,2" returnArray.get(0) == "Hello\\, how are you" returnArray.get(1) == "2"
void	setFunctionArgumentStack(FormulaVariableStack functionArgumentStack)
protected FormulaVariable	solve(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) Actual method to be overridden.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

functionArgumentStack

protected FormulaVariableStack functionArgumentStack

The stack containing the function's arguments. It will also contain the result of this function once solved. and these functions should set thestack's highestLevelInSolution.

Constructor Detail

FormulaFunction

public FormulaFunction(FormulaVariableStack functionArgumentStack)

Create a new FormulaFunction with an already defined functionArgumentStack.

Parameters:

functionArgumentStack - a list of FormulaVariables that are needed by the function.

FormulaFunction

public FormulaFunction(java.lang.String functionArgumentString)
                throws java.text.ParseException

Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function

Parameters:

functionArgumentString - the string representing the functions arguments. The outer parentheses must be removed.
Example: If the function is IIF(AThrows:

java.text.ParseException - if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)

FormulaFunction

public FormulaFunction(java.lang.String functionArgumentString,
                       int level)
                throws java.text.ParseException

Create a new FormulaFunction with a comma-delimited string representing the arguments needed by the function

Parameters:

functionArgumentString - the string representing the functions arguments. The outer parentheses must be removed.
Example: If the function is IIF(Alevel - the level applied to the creation of FormulaVariables for the arguments.

Throws:

java.text.ParseException - if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)

FormulaFunction

public FormulaFunction(FormulaVariable functionVariable)
                throws java.text.ParseException

Create a new FormulaFunction from the functionVariable (A FormulaVariable of TYPE_FUNCTION).
This is the most common constructor used.

Parameters:

functionVariable - a FormulaVariable of TYPE_FUNCTION

Throws:

java.text.ParseException - if arguments can't be parsed using parseCommaDelimitedFunctionFields(String,int)

Method Detail

function

public FormulaVariable function(FormulaVariableStack functionArgumentStack,
                                FormulaVariableList variableList,
                                int iteration,
                                SupportParameters supportParameters,
                                FormulaFunctionList functionList,
                                int resolveEverythingAboveLevel)
                         throws java.text.ParseException,
                                java.lang.ArithmeticException,
                                java.lang.ClassNotFoundException

Programmer defined function.
This function replaces the funcionArgumentStack and calls function(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) so you can leave this function alone, but the other function needs to be overriden.

Parameters:

functionArgumentStack - list of variables needed by function to return result.

variableList - the variable list used when solving for various variables.

iteration - used to prevent infinite loops.

supportParameters - a list of objects that this method may need to solve itself. One example is if this were an SQL function, one of the objects could be an sql connection.

functionList - list of functions that may be necessary when solving FormulaVariables on the functionArgumentStack.

resolveEverythingAboveLevel - reflects level at which TYPE_VARIABLE, TYPE_FUNCTION, and TYPE_FORMULA variables need to be re-solved.

Returns:

FormulaVariable containing the result

Throws:

NoClassFoundException - if solving the arguments requires access to an undefined function.

ArithmeticException, - ParseException as handed through from FormulaVariableStack and if caused by various solutions in certain functions. SQL functions and the like will have to throw ArithmeticExceptions since we are faily generic here. If you add your own exceptions in your functions, note that it is up to you to support the exception if it fails when being solved in the FormulaVariableStack because it will be thrown as an unexpected exception. You are better off using the Arithmetic Exception in your defined function and setting the return message such that your external code can react appropriately to the error..

java.text.ParseException

java.lang.ArithmeticException

java.lang.ClassNotFoundException

function

public FormulaVariable function(FormulaVariableList variableList,
                                int iteration,
                                SupportParameters supportParameters,
                                FormulaFunctionList functionList,
                                int resolveEverythingAboveLevel)
                         throws java.text.ParseException,
                                java.lang.ArithmeticException,
                                java.lang.ClassNotFoundException

Programmer defined function. By default this method calls the solve(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) throws java.text.ParseException, java.lang.ArithmeticException method.
You must either override this method or override the following method.
protected FormulaVariable solve(FormulaVariableList variableList, int iteration, SupportParameters supportParameters, FormulaFunctionList functionList, int resolveEverythingAboveLevel) throws java.text.ParseException, java.lang.ArithmeticException.
If you want to override the help instructions then override this method, otherwise it is easier to override the solve method.

Parameters:

variableList - the variable list used when solving for various variables.

iteration - used to prevent infinite loops.

supportParameters - a list of objects that this method may need to solve itself. One example is if this were an SQL function, one of the objects could be an sql connection.

functionList - list of functions that may be necessary when solving FormulaVariables on the functionArgumentStack.

resolveEverythingAboveLevel - reflects level at which TYPE_VARIABLE, TYPE_FUNCTION, and TYPE_FORMULA variables need to be re-solved.

Returns:

FormulaVariable containing the result

Throws:

java.lang.ArithmeticException - or ParseException as handed through from FormulaVariableStack and if caused by various solutions in certain functions. SQL functions and the like will have to throw ArithmeticExceptions since we are faily generic here. If you add your own exceptions in your functions, note that it is up to you to support the exception if it fails when being solved in the FormulaVariableStack because it will be thrown as an unexpected exception. You are better off using the Arithmetic Exception in your defined function and setting the return message such that your external code can react appropriately to the error..

java.text.ParseException

java.lang.ClassNotFoundException

getName

public static java.lang.String getName()

Returns:

the name of this function

getRequiredSupportParameters

public static java.lang.String[][] getRequiredSupportParameters()

Returns:

String[][] of needed classes supplied by SupportParameters in the form of {ParameterName, ParamaterClass} such as {{"Connection","java.sql.Connection"},{"Panel","javax.swing.JPanel"}}

getRequiredFormulaVariables

public static java.lang.String[][] getRequiredFormulaVariables()

Returns:

String[][] of needed FormulaVariables and their dataTypes such as {{"EmployeeName","TYPE_STRING"},{"BirthDate",TYPE_DATE"},{"CurrentDate","TYPE_DATE")}

getRequiredArguments

public static java.lang.String[][] getRequiredArguments()

Returns:

String[][] of needed arguments and their dataTypes which as {{"Test Argument ARG1","TYPE_BOOLEAN"},{"True Argument ARG2","TYPE_?"},{"False Argument ARG3","TYPE_?"}}
If handing this routine a FormulaVariableStack functionArgumentStack then the FormulaVariable arguments should be named, ARG1, ARG2, etc...

getFunctionArgumentStack

public FormulaVariableStack getFunctionArgumentStack()

Returns:

the current functionArgumentStack.

setFunctionArgumentStack

public void setFunctionArgumentStack(FormulaVariableStack functionArgumentStack)

Parameters:

functionArgumentStack - set the new functionArgumentStack. The functionArgumentStack is usually set once, then this class is created.

getReturnValueDescription

public static java.lang.String[] getReturnValueDescription()

Returns:

String[] description of the return value as well as it's data type

getFunctionArgumentStackFromFunctionVariable

protected static FormulaVariableStack getFunctionArgumentStackFromFunctionVariable(FormulaVariable functionVariable)
                                                                            throws java.lang.ArithmeticException,
                                                                                   java.text.ParseException

Parameters:

functionVariable - create a functionArgumentStack from the data contained in a FormulaVariable of TYPE_FUNCTION.

Throws:

ArithmeticException, - ParseException

java.lang.ArithmeticException

java.text.ParseException

parseCommaDelimitedFunctionFields

protected static FormulaVariableStack parseCommaDelimitedFunctionFields(java.lang.String formulaSegment,
                                                                        int level)
                                                                 throws java.text.ParseException,
                                                                        java.lang.ArithmeticException

Break the contents of a formula that are between parentheses into their constituent fields.
Note: Examples are as seen in code, so "\\\"how\\\"" creates the string \"how\" and Hello\\, creates the string Hello\,
Ex: "IIF(A formulaSegment = "A returnArray.get(0) == "A returnArray.get(1) == "\"Hello there, \\\"how\\\" are you\""
returnArray.get(2) == "1.34"
Escaping a comma will cause the comma to be ignored.
Ex: "Hello\\, how are you,2"
returnArray.get(0) == "Hello\\, how are you"
returnArray.get(1) == "2"

Parameters:

formulaSegment - the contents between parentheses in a formula.

level - the level at which the variables in the newly created stack should be stamped. Usually level zero unless you have record specific information in the formulaSegment. Ideally, variables should be used when referencing record specific data so that the function only recalculates the result if the resolveEverythingAboveLevel value falls below the highestLevelInSolution recorded in this new stack.
The variable names within the stack will be labeled ARG1, ARG2, ARG3, etc...

Returns:

a formulaVariableStack making up the comma separated fields in a function.

Throws:

java.lang.ArithmeticException - or ParseException as handed through from FormulaVariableStack.

java.text.ParseException

solve

protected FormulaVariable solve(FormulaVariableList variableList,
                                int iteration,
                                SupportParameters supportParameters,
                                FormulaFunctionList functionList,
                                int resolveEverythingAboveLevel)
                         throws java.text.ParseException,
                                java.lang.ArithmeticException,
                                java.lang.ClassNotFoundException

Actual method to be overridden.

Throws:

java.text.ParseException

java.lang.ArithmeticException

java.lang.ClassNotFoundException