Develop a Custom Function in Java

Overview

Create the function on the server

Error handling

Overview

General steps:

  1. Create the code for the Java function on the integration engine server.
  2. Each Custom Function must be packaged in a dedicated .jar file. This archive file must contain a manifest file that defines the Custom Function class using "Main-Class" entry.
  3. Place the jar file in the folder:
  4. $CORE_LOCAL/java/dmlfunctions
  5. Optionally the manifest can also define the Custom Function class path with additional .jar files. In this case, you place the additional .jar files in this same folder.
  6. Manifest file example:
  7. In Mapping Services, create a Custom Function object that references the Java function on the integration engine server.
  8. On the General tab of the Custom Function Properties view, in the Use Channel field:
  9. Select SAP if your Custom Function returns a value via the SAP RFC interface
  10. Select JDBC if your Custom Function requires a connection to a data base via a JDBC channel
  11. Otherwise, use the None default value
  12. In Mapping Services, in an Integration Process object, create a Mapping Flow with a DML expression that calls the Custom Function.
  13. In Mapping Services, create an Integration Task object to link the Integration Process processing sequence to real server tasks:
  14. If your Custom Function returns a value via an RFC to SAP, in the Integration Task Configuration tab, select the Custom Function name and then in the Custom Function Configuration pane, select a SAP Channel from the list of available channels.
  15. If your Custom Function requires a connection to a data base via JDBC, in the Integration Task Configuration tab, select the Custom Function name and then in the Custom Function Configuration pane, select a JDBC Channel from the list of available channels.
  16. In Mapping Services, Execute a Send to Server command on the Integration Task.
Note The signature of the function is not verified during the Send to Server operation. If the function referenced by the Java Custom Function object does not exist on the server, an error is not generated until the integration is executed.

Create the Java function on the server

To write the code for a Java function that is referenced by an integration engine Custom Function object, you must create a class that implements the function. This class contains the method that takes an array of java.lang.Object as the entry argument, and returns a java.lang.Object object.

The person who develops the function must retrieve the entry arguments and assign types to them according to what has been defined in the Mapping Services Custom Function definition.

For each DML data type there must be a corresponding standard Java object as shown in the following table:

DML Java

Boolean

java.lang.Boolean

Integer

java.lang.Integer

String

java. lang.String

Real

java.lang.Double

Date

java.util.Date

VLO

byte[ ]

Notes:

  • byte[ ] is seen as a java.lang.Object.
  • Java does not distinguish between the values null and absent. If an object in DML is null or absent, in Java we receive the null value in the object array. Similarly, when the null value is received as a return value, it is considered as null in DML.

Example 1: Java code

Access to the JDBC Channel

If the Java function uses a JDBC Channel, the first element of the argument table must be an object that implements the interface javax.sql.DataSource

This object is defined at the following URL:

http://java.sun.com/j2se/1.5.0/docs/api/javax/sql/DataSource.html

From this object you can use the Map Engine JDBC API to access databases.

Example 2: Java code with JDBC database access

RFC access to SAP

If the Java Custom Function requires the RFC interface to SAP, the first element of the argument array is an object that implements the interface JCO.Client(com.sap.mw.jco.JCO).

A SAP-type Java Custom Function takes input values of any of the following types:

  • Boolean
  • String
  • Real
  • Integer

From this object you can use SAP JCO to communicate with SAP.

Example 3: Java code with RFC to SAP

Error handling

All exceptions that are either returned or not caught by the user Java function provoke an error status on the current transaction. In this case the Java stack is visible in the trace viewer.

Possible errors are listed in the following table.

Cause Error message Solution

The class specified in Mapping Services was not found.

custom class <class> not found. must be in a compiled JAR file in CORE_LOCAL/java/dmlfunctions/

Compile the class to a .jar file and place the .jar in the correct directory folder.

Check to confirm that the .jar file contains a manifest file defining the main class.

The method specified in Mapping Services was not found.

custom method <method> not found.

Confirm that the method is public and has the same name as the name specified in the Mapping Services Custom Function object.

The input argument type of the DML function does not correspond to the type expected by the Java method.

exception occurred in custom function <method>

<method call stack>

Modify the input argument type so that it corresponds to the type specified in the Mapping Services Custom Function object, or in the Java code, modify the object type of the object to be retrieved.

The output argument type does not correspond.

invalid output type for the custom method <method>

Modify the output argument type in the Mapping Services Custom-Funtion, or in the Java code, modify the object type of the object to be returned.

The object passed in the argument to the Java method is null.

exception occurred in custom function <method>

<method call stack>

Confirm that the objects passed to the Java method in input do not contain null values.

The Java function does not have the correct signature.

custom method <method> mismatches. must be like: Object methodName(Object[] args)

Confirm that the Java method uses the prototype:

Object methodName(Object[] args)

The Java function generates an exception.

exception occurred in custom function <method>

<method call stack>

Verify whether or not the Java method handles exceptions.

Communication with JVM has failed

Java C Interface failure: <method jni>

Check the JVM configuration

Related topics

Use Custom Functions

Related Links