Custom Functions

Custom Function Registration. 2

Creating the Java Program.. 3

Programming notes 5

Testing the Java Program outside of Ebase. 6

Extending FPL Language Syntax. 7

To add a Function to the FPL.jj file: 7

Generating the UfsLanguage.jar file. 8

Replacing the UFSLanguage.jar File. 9

Adding your Java functions to the Ebase server CLASSPATH. 9

Overview

If you are considering writing a custom function, you might also consider using an API based scripting language (e.g. Javscript) to access Java classes directly. Click here for details.

The Ebase form processing language (FPL) can be extended with user custom functions. Once a custom function is made available to Ebase it can be used within any processing script. As with system provided functions e.g. uppercase, lowercase etc, custom functions can be nested with other functions, can appear in any expression, and may take any Ebase fields or other functions as parameters.

e.g. if repayment(loan, years, interestRate, mortgageType) is defined as a custom function then valid usage within FPL would include

set field1 = repayment(field1, field2, 5.0, field3);

if [repayment(field1, field2, 5.0, field3) > Field5] then ...

set Premium = repayment(field1, field2, 5.0, round(field3)) + F6;

Each custom function is mapped to a Java class. Whenever the Ebase form processor comes across a custom function during form script execution it will automatically call the mapped Java class and pass any defined parameters. Ebase achieves this by instantiating the class which must be written to a specific specification (see below) and executing the run() method on that class. The run() method contains the programming logic to execute the custom function.

Please note that at runtime, custom function classes are instantiated once, then used many times for different forms and different users. For this reason, they should not contain instance level variables. See programming notes.

Custom functions enable data from any application that exists outside of the Ebase environment to be incorporated into form processing logic. Equally, they allow data to be written directly from an Ebase form to any external application. Custom functions are called from FPL scripts which themselves are executed via the Event Model implemented by Ebase.

A custom function might be used to:

execute other programming languages
communicate directly via "connectors" with a wide range of ERP applications e.g. SAP R3, BAAN
communicate with a wide range of vendor applications via supplied APIs
call EJB services

Custom functions are limited in that they can only return a single value. Custom resources should be used to communicate with external systems or interfaces where more complex data structures are needed.

Creating a Custom Function

Creating a custom function requires a number of discreet steps:

Register the custom function to Ebase.
Create the Java class that the custom function is mapped to.
Add the custom function syntax to the FPL language definition.
Add the compiled class plus any other classes required to the Ebase CLASSPATH.

Custom Function Registration

Custom functions are registered using the Ebase Designer. Registration requires the following:

Name of the custom function e.g. repayment.
Class name of the Java program that the custom function maps to. This is the fully qualified class name e.g. com.ebasetech.ufs.customfunctions.Repayment
Return type of the function e.g. boolean, String etc.
Parameters required by the function and their data types.

The custom function registration is initiated from the tools menu (Tools --> Maintain functions)

Creating the Java Program

The Java program must extend UFSCustomFunction as shown in the example below:

/**

* Class : Repayment

* Function : Provides run time mapping to the Ebase repayment custom function.

import java.util.*;

import org.nfunk.jep.*;

import com.ebasetech.ufs.function.*;

import com.ebasetech.ufs.kernel.*;

public class Repayment extends UFSCustomFunction {

/**

* Constructor

public Repayment(UFSFormInterface formInterface) {

super(formInterface);

/* specify the number of parameters to be received by this custom function */

numberOfParameters = 4;

}

/**

* Function : Custom function to perform a mortgage repayment recalculation.

* Parameters : loan : amount of loan

* intRate : interest rate

* years : repayment period

* repaymentType : I for Interest Only, R for Repayment

public void run(Stack inStack) throws FormException, ParseException {

// check the stack

checkStack(inStack);

// get the parameter from the stack

Object param1 = inStack.pop();

Object param2 = inStack.pop();

Object param3 = inStack.pop();

Object param4 = inStack.pop();

// check whether the argument is of the right type

if ( param1 instanceof String

&& param2 instanceof Double

&& param3 instanceof Double

&& param4 instanceof Double) {

// set up the passed parameters...

double loan = ((Double) param4).doubleValue();

double intRate = ((Double) param3).doubleValue();

double years = ((Double) param2).doubleValue();

String repaymentType = param1.toString();

// perform the function...

double rate = intRate / 100;

double top = loan * rate;

double bot;

if (repaymentType.equals("I")) {

bot = 1;

} else {

bot = 1 - 1 / Math.pow(rate + 1, years);

}

double amt = (top / bot) / 12;

amt = Math.round(amt * 100) / 100.0;

// push the result on the inStack

inStack.push(new Double(amt));

} else {

throw new ParseException("Invalid parameter type");

}

Notes:

1. The class must extend the UFSCustomFunction class.

2. The number of parameters to be received by the function must be set in the constructor. Please do not place any additional code in the class constructor. See programming notes.

3. Instance level variables must not be used. See programming notes.

4. Parameters are always received via a Stack object.

5. Once parameters are retrieved from the stack their type must be checked. If the type does not match the expected type then an exception must be thrown.

6. The result of the function is returned via the Stack.

At execution time i.e. when FPL finds a custom function, the Ebase form processor will instantiate the Class mapped to the custom function and will execute the run() method of that Class.

Programming notes

1. The form external interface class is made available to the function class. This can be used to directly access and change form attributes such as current page, field values etc. (See Ebase External Interface for more information) This can be used by referring to attribute formInterface e.g.

String currentPage = formInterface.getCurrentPage();

2. Function classes are shared between users and must not contain any instance level variables.

For example, do not do this:

public class Repayment extends UFSCustomFunction

{

private Object var1; // this is an instance level variable

public void run(Stack inStack) throws FormException, ParseException

{

var1 = createObject();

Instead, create new objects only inside methods:

public class Repayment extends UFSCustomFunction

{

public void run(Stack inStack) throws FormException, ParseException

{

Object var1 = createObject(); // this is a method level variable

3. Functions should signal errors by throwing either a ParseException or a FormException. ParseException should be thrown for command syntax errors and FormException for other runtime problems. Both of these will result in termination of the form and logging of the error. In addition, if the system is in test mode, the error message will be displayed on the HTML page and the execution log. e.g.

if ( errorCondition )

{

throw new FormException("Description of this particular error");

}

4. Functions wishing to return an integer, say int myInt, should return a Double representing the value. e.g.

inStack.push(new Double(myInt));

5. Functions wishing to return a boolean, should return a Double containing the value 0.0 for false and 1.0 for true.

Testing the Java Program outside of Ebase

The following Java is an example of a test program for the Repayment function above. It enables the Java Class which implements the custom function to be tested before integration with Ebase.

/**

* Class : RepaymentTest

* Function : Tests the repayment custom function.

import org.nfunk.jep.*;

import com.ebasetech.ufs.kernel.*;

class RepaymentTest {

/**

* Constructor.

public RepaymentTest() {}

/**

* Main method. Test of the repayment custom function.

public static void main(String args[])throws FormException{

double value;

// create a new parser...

JEP parser = new JEP();

// define an expression to test the repayment function...

String expr = "repayment(10000,25,5,\"R\")";

// add the function class to the expression evaluator...

parser.addFunction("repayment",

new com.ebasetech.ufs.customfunctions.Repayment(null));

// now parse the expression...

parser.parseExpression(expr);

if (parser.hasError()) {

System.out.println("Error while parsing");

System.out.println(parser.getErrorInfo());

return;

}

// now retrieve the result from evaluating repayment function...

value = parser.getValue();

if (parser.hasError()) {

System.out.println("Error during evaluation");

System.out.println(parser.getErrorInfo());

return;

}

System.out.println(expr + " = " + parser.getValue());

}

Extending FPL Language Syntax

In order to use a custom function within FPL the definition of the function must be added to FPL Script Command Syntax. This is necessary because FPL syntax must be accurately checked when creating scripts within the Ebase Designer. Language syntax checking is invoked when the verify button is clicked within the script editor.

Ebase stores the FPL language definition in Extended Bachus Naur Form (EBNF) and uses JAVACC, a Java compiler compiler from Sun Microsystems, to generate language syntax checking software (Java).

The process of adding a new function to FPL is as follows:

Add the custom function definition to the FPL language definition.
Generate the new language syntax checking software.
Incorporate the generated software into a Java package called com.ebasetech.ufs.parse
Add the package to a Jar file called UFSLanguage.jar
Replace the existing UFSLanguage.jar used by Ebase.

The FPL language definition is stored in file FPL.jj, which is included in the LanguageBuilder/Fpl directory of the Ebase distribution. The FPL.jj file is a text document.

To add a Function to the FPL.jj file:

1. Open the FPL.j in a text editor.

2. Add the name of the function to the section below

/***********************************************

* Custom function token definitions added below

***********************************************

{

< STARTSWITH: "STARTSWITH">

| < ENDSWITH: "ENDSWITH">

| < CONTAINS: "CONTAINS">

| < UPPERCASE: "UPPERCASE">

| < LOWERCASE: "LOWERCASE">

| < SUBSTRING: "SUBSTRING">

| < ROUND: "ROUND">

| < TOSTRING: "TOSTRING">

| < DAYOFWEEK: "DAYOFWEEK">

| < DATETOSTRING: "DATETOSTRING">

| < REPAYMENT: "REPAYMENT">

}

3. Also add the function to the following section

/********************************************************

* Add custom function to the Function() definition below

********************************************************

void Function() :

{}

{ ( StartsWith() | EndsWith() | Contains() | Uppercase() | Lowercase() | Substring() | Round() |

Tostring() | DayofWeek() | DateToString() |

Repayment()

)

}

4. Lastly, add the function definition to the following section

/****************************************

* Custom function definitions added below

****************************************

void Repayment() :

{}

{

<REPAYMENT> <LPAREN> Expression() <COMMA> Expression() <COMMA> Expression() <COMMA> Expression() <RPAREN>

}

The repayment function definition is shown as an example. The example represents a function called repayment, which accepts four comma-delimited parameters, each of which can be an expression. An expression can be any combination of literals, constants, field names, operators and other functions.

If your function has syntactical requirements beyond this example please contact Ebase Technology Technical Support for assistance.

Once the FPL.jj file has been amended, the language syntax checking software must be generated.

Generating the UfsLanguage.jar file

Double click on file ufsLanguageBuilder.jar in directory LanguageBuilder of the Ebase distribution to invoke the language builder application as shown below:

Navigate to the amended FPL.jj, specify the location for the target jar file, then click Build. This will build a UFSLanguage.jar file to the loacation you have specified.

Replacing the UFSLanguage.jar File

The UFSLanguage.jar file is required by the designer only. It's location will vary according to the installation. Typically, it will be in folder .../UfsClient/lib. Copy the new file to the designer.

Adding your Java functions to the Ebase server CLASSPATH

On the server, add jar files to directory .../ufs/WEB-INF/lib and class files to directory .../ufs/WEB-INF/classes. Jar files and classes added to these directories are automatically added to the Ebase web application classpath. If classes are added, the directory structure beneath the classes directory must match the full package name of the Java class exactly, respecting case. e.g. class abc.xyz.MyClass.class would result in the structure /WEB-INF/classes/abc/xyz/MyClass.class.