Creating Custom Functions

In addition to the Math- and String-related custom functions provided with Presentation Builder, you can create your own custom functions to extend functionality within your applications. New custom functions can be created using any editor or IDE that supports creation of Java code. In this version of Presentation Builder, Java is the only supported language for custom functions.

A custom function must be implemented as a Java class, following Java bean conventions. This means that the custom function must either provide a Java BeanInfo class, or use set methods for inputs and get methods for outputs. Presentation Builder uses reflection to parse a custom function and locate read and write methods.

Input and output data must be in String format. Each function implementation is responsible for converting String values to the appropriate data type. There is no limitation on the number of input and output values supported. All input values are passed in through the set methods, and output values are obtained through get methods.

Note You can also create custom functions to implement specific host communications or synchronization. The interfaces and methods provided to support these custom functions are defined in the QACOM API. For details, see the QACOM API topic.

Creating Custom Functions Using Java Beans

You can create custom functions as Java beans, and then add the Java beans to a JAR file. The JAR file can then be added to a Presentation Designer library. All custom functions must implement the Java interface com.attachmate.pb.function.IFunction. The interface is contained in the PresentationServer.jar file, which is installed with Presentation Builder. Because the interface is contained in the atm_functions.jar file, the folder containing the file must be included in the classpath for your project to successfully compile your custom functions.

The custom functions you create must also have an associated manifest file that includes an entry for every function bean class. The manifest file is used by Presentation Designer to identify function classes within JAR files without having to load the full JAR file.

Note You must have the Java Development Kit (JDK) installed in order to successfully create a custom function.
To create a custom function as a Java bean
  1. Using your IDE or a text editor, develop your function class as a Java bean and implement the interface com.attachmate.pb.function.IFunction.

    The IFunction interface is contained in the atm_functions.jar file, which, to compile your custom functions, must be included in your classpath. The default location for this file is C:\Program Files\Attachmate\EAI\PresentationDesigner\lib.

    Refer to the following sample code to implement the IFunction interface:

    	package com.attachmate.pb.function;
    	public Interface IFunction
    	{
    	public void Run() throws Exception;
    	}
    	
    Note Implement the Run() method to perform the logic of the function.
  2. Create a manifest file, and then save it as my_manifest.mf in the same folder as the custom function class files.

    This file must include entries for all function classes, with an empty line before each entry; otherwise, the JAR utility reads the first entry as the header for the file.

    Following is a sample manifest file:

    	Manifest-Version: 1.0
    	
    	Name: com/abc/functions/database/Account.class
    	Function: True
    	
    	Name: com/abc/functions/support/Account.class
    	Function: True
    	
    Note If you do not provide a manifest file, all of the custom functions in the JAR will be listed in the under the library entry in the Select Function dialog box.
  3. (Optional) Use the JAR utility, jar.exe, which is part of the Java Development Kit (JDK), to bundle your function bean classes into a JAR file, and then include the manifest file, my_manifest.mf, which was created in the preceding step.

    Run from the command prompt, the following (example) command creates a new JAR file named my_functions.jar, which incorporates all class files from the \my_classes folder, including subfolders and the manifest file my_manifest.mf.

    jar cvfm my_functions.jar my_manifest.mf -C my_classes

    Note Each JAR file can also contain other classes, such as those that support your custom function.

Although it is not required, when implementing a function as a Java bean you can create a Java bean standard BeanInfo class to provide explicit bean information about the specified function bean.

To use a BeanInfo class
  1. Append BeanInfo to the function bean class name.

  2. Include the BeanInfo class in the same package with the function bean.

    When the BeanInfo class is not present, the function bean is analyzed using reflection to discover the read and write methods. For details, see the Java Development Kit (JDK) documentation.

Sample Custom Functions

The following sample demonstrates how to create a simple function object that reverses a string:

package samples;

 public class ReverseString
 implements com.attachmate.pb.function.IFunction
 {
    private String in  = "";
    private String out = "";

    public void setInput(String in)
    {
       if(in==null)
          return;

       this.in = in;
    }

    public String getOutput()
    {
       return out;
    }

    public void run() throws Exception
    {
       out = (new StringBuffer(in)).reverse().toString();
    }
 }

The following sample custom function is a simple QACOM function object that returns the name of the current screen. When the init method of the IQAScreenFunction interface is called, the function object typically assigns the IQAScreenFactory object to a member variable for use when the run method is invoked.

package qacomsamples;

 import com.attachmate.pb.qacom.*;
 import com.attachmate.pb.function.*;

 public class GetCurrentScreen implements IFunction, IQAScreenFunction
 {
    private IQAScreenFactory m_factory       = null;
    private String           m_currentScreen = "";

    public String getCurrentScreen()
    {
       if(m_currentScreen==null)
          m_currentScreen = "";
       return m_currentScreen;
    }

    public void init(com.attachmate.pb.qacom.IQAScreenFactory in)
    {
       m_factory = in;
    }


    public void run() throws Exception
    {
       IQAScreen qas = m_factory.getInstance("MyHost");
       if(qas==null)
          throw new IllegalArgumentException("No QACOM object for host=MyHost");

       m_currentScreen = sss();
       return;
    }
 }
Related Topics
Bullet Custom Functions, Overview
Bullet Using Custom Functions
Bullet Installing Custom Functions
Bullet QACOM API
  Attachmate