Writing Custom Functions

The custom function available for use with Transformer must be written in Java code and stored in the following directory:

Note: The following section is written assuming that you are familiar with the Java programming language.

Each custom function you write must be a subclass of the AbstractFunction super class.

You must implement a constructor for your class and the two abstract methods, execute() and getReturnType(), which are inherited from the AbstractFunction class. You may also choose to add your own methods. The Java code for your custom function must conform to the following format:

Import Statement

You must include the following import statement in the beginning of your custom function implementation:

import com.iwaysoftware.transform.common.function.AbstractFunction;

This enables you access to the methods required for your custom function implementation.

Note: Optionally, you can utilize the logging capabilities of Transformer in the code of your custom function by including the following import statements in the beginning of your custom function implementation:

import com.iwaysoftware.transform.common.log.LogUtil;
import com.iwaysoftware.transform.common.log.TransformLogger;

Class Declaration

As stated previously, a custom function is a subclass of the AbstractFunction super class. Therefore, you can declare your custom function as follows:

public class MY_FUNCTION_NAME extends AbstractFunction {
...
}

where:

MY_FUNCTION_NAME: Is the name of your custom function.

Constructor

There are two methods you must call within the constructor of your custom function. They are the setName(String name) and setDescription(String description) methods, which are pre-defined in the AbstractFunction super class. The values provided as parameters for these methods are utilized when you access your custom function within Transformer.

The name of the function used in Transformer is the parameter that you set using the setName method, and the description of the function used by Transformer is the message you type as the parameter in setDescription.

execute( )

The method execute(), is one of two abstract methods declared in the AbstractFunction super class, which is supposed to contain the function procedures and instructions. Your custom function, which is a subclass of AbstractFunction, must therefore, implement the execute() method as follows:

public Object execute() throws Exception {
...
}

When you are writing the body of this method, you can follow the same style that is used to write any method in Java.

Getting Arguments

Retrieving arguments passed into your custom function is achieved through the methods getValueInstance(), getArgument(int index), and getFunctionContext(), which are the pre-defined methods from the functions package that your custom function is a part of. To store two arguments as String variables argOne and argTwo, write the following:

String argOne = 
(String)getFunctionContext().getArgument(0).getValueInstance();

String argTwo = 
(String)getFunctionContext().getArgument(1).getValueInstance();

Other methods that you may find useful for your custom function implementation are:

getNumberOfArguments()
Returns an integer indicating the number of arguments passed to your function by the user, which is used in conjunction with method, getFunctionContext(), as follows:
```
int num = getFunctionContext().getNumberOfArguments();
```
getArguments()
Returns an array containing all of the arguments passed to your function by the user. To store your arguments in an array of objects called myArray, use the following format:
```
Object[] myArray = getFunctionContext().getArguments();
```

getReturnType( )

getReturnType() is one of the abstract methods declared in the AbstractFunction class. Therefore your custom function, which is a subclass of AbstractFunction, must implement this method. The value returned by getReturnType() indicates the type of value you return in method execute(). The choices for your return value are:

java.lang.Boolean.class
java.lang.Character.class
java.lang.Double.class
java.lang.Float.class
java.lang.Integer.class
java.lang.Long.class
java.lang.String.class
java.lang.StringBuffer.class

Associated Object Map

The custom function interface of Transformer is now updated with the ability to utilize the data structure of customizable global parameters. This data structure is implemented as a Java Map object, which is an object that maps keys to values. This object can be accessed by any custom function within your project. As a result, it can contain global reusable data or information that can be cached, such as your database connection string. The Associated Object Map can also be used to track the usage of the custom functions in your project, if required. Use the following format to access the Associated Object Map:

Map objectMap = super.getAssociatedObjectMap();

Sample Custom Function

The following snippet of Java code is the implementation for a custom function that returns a string resulting from adding 25 to the input value of the function.

import java.math.BigDecimal;
import java.util.Map;
import com.iwaysoftware.transform.common.function.AbstractFunction;
import com.iwaysoftware.transform.common.log.LogUtil;
import com.iwaysoftware.transform.common.log.TransformLogger;
public class ADD25
            extends AbstractFunction
{
      private static final BigDecimal BD25 = new BigDecimal(25);
      public ADD25()
      {
           /* specifies the function name to be used within iAM */
           setName("ADD25");
           /* specifies the function description to be used within iAM */
           setDescription("Return a string resulting from adding 25 to input value.");
      }
      public Object execute()
                  throws Exception
      {
           /*
            * retrieves the first argument and assigns it to Double variable
            * 'input'
            */

           // arguments are String always
           String inputArg = (String) 
getFunctionContext().getArgument(0)
                                    .getValueInstance();
           BigDecimal input;
           try
           {
               input = new BigDecimal(inputArg);
           }
           catch (Exception e)
           {
               input = new BigDecimal(0);
           }
           // Gets the instance of the logger
           TransformLogger logger = super.getLogger();
           // Gets the debug flag
           boolean debug = LogUtil.canDebug(logger);
           // Fetches associate objects
           Map objectMap = super.getAssociatedObjectMap();
            /* creates a variable to hold the value that will get returned */
           String answerString;
           if (objectMap.containsKey(input))
           {

               // return stored result
               String result = (String) objectMap.get(input);
               if (debug)
               {
                        LogUtil.debug(false, logger, "returning CACHED result: ");
               }
               return result;
           }
           else
           {
                       answerString = input.add(BD25).toString();
               objectMap.put(input, answerString);
               if (debug)
               {

                         LogUtil.debug(false, logger, "returning the value : "
                     + answerString);
               }
               // return string
               return answerString;
           }
    }
    public Class getReturnType()
    {
           /* specifies that method execute() returns a String */
           return java.lang.String.class;
    }