Working With Functions

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 iIT 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;

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.

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 predefined in the AbstractFunction super class. The values provided as parameters for these methods are utilized when you access your custom function within iIT Transformer.

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

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.

Retrieving arguments passed into your custom function is achieved through the methods getValueInstance(), getArgument(int index), and getFunctionContext(), which are the predefined 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() 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

The custom function interface of iIT 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();

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;
    }

In order to make your custom function available for use within iIT Transformer, you need to compile the completed Java code of your custom function, integrating it with the Transformer engine code to create a .class file.

To compile custom functions, the %IWAY_HOME%/lib path must be part of your building environment. For example, you can use the following script to compile your custom function(s) with JDK version 1.6:

set IWAY_HOME=%IWAY7%
set LIB="%IWAY_HOME%lib/*"
set CLASS_FILES=%IWAY_HOME%etc/manager/transformations/custom_functions
set SOURCE_FILES=C:/temp/iway_custom_functions/src/*.java
javac -classpath %LIB%; -d %CLASS_FILES% %SOURCE_FILES%
@pause

where:

C:/temp/iway_custom_functions/src/

Is the temporary location for your custom function(s) source files on your hard drive.

In early versions of Transformer, for example, 5.2.104, the Java code for a custom function had a format similar to the following:

import com.xmlglobal.goxmltransform.engine.functions.*;
public class MY_FUNCTION_NAME extends AbstractFunction
{
  public MY_FUNCTION_NAME()
  {
    setName("MY_FUNCTION_NAME");
    setDescription("This is what my function does...");
  }
  public Object execute() throws Exception
  {
    // perform function's execution here
    // and return desired output value
  }
  public Class getReturnType()
  {
    return MY_FUNCTION'S_RETURN_TYPE;
  }
}

where:

MY_FUNCTION_NAME

Is the name of your custom function.

MY_FUNCTION'S_RETURN_TYPE

Is the data type of your custom function's return value.

The following procedure describes how to migrate custom functions created for the early versions of Transformer, for example, 5.2.104, to be called by your modified .xch file.

Note: Before you compile the migrated custom functions, verify that the iwtranse.jar file is in your classpath.

In iIT Transformer, the functionality of custom functions for run time purposes is the same as the design time functionality. For more information on configuring custom functions, see Custom Functions.