Message Image  

How to use Java in a Message Map (Graphical data map) in IBM Integration Bus?

 View Only
Tue July 14, 2020 05:17 AM

In the Graphical Data Mapping editor, you can use methods in a Java class to define a transformation, to define a conditional expression, or to change the value of an input parameter in another function. This article provides guidelines on how to design your Java methods and shows you how to use Java in a message map (also known as a graphical data map).

  • Guidelines to design a Java method to transform simple types
  • Guidelines to design a Java method to transform complex or repeating types
  • Mapping an element by using a Custom Java transform
  • Define a conditional expression
  • Alter the value of an input argument to an XPath function

Guidelines to design a Java method to transform simple types

The Java class that you provide to a map must have a static method that returns the appropriate type for the value of the output element, and takes parameters of the appropriate type for the wired inputs.

For example, the following Java method can be used in a Custom Java transform that has three input elements, of types xs:string, xs:decimal, and xs:boolean, and the output element has a xs:decimal type:

public static BigDecimal calSomething(String memType, BigDecimal stdCost, boolean flag) {
		BigDecimal actualCost = stdCost;
		if (flag & memType.startsWith("gold")) {
			BigDecimal discRate = new BigDecimal(0.9);
			actualCost = actualCost.multiply(discRate);
		}			
		return actualCost;
	}

Guidelines to design a Java method to transform complex or repeating types

You can use a Custom Java transform to process input and outputs that are arrays or complex types. You must pass the data by using the IBM Integration Bus Java plugin API MbElement Java class.

You use the MbElement class in a Java method to pass a complex type, a wildcard xsd:any, or a wildcard xsd:anySimpleType.

You use the Java MbElement class for mapping inputs and outputs that are not simple types with a Custom Java transform.

Using the MbElement class

To use the MbElement class in the Java code that you use in a map, complete the following tasks:

  1. Add the MbElement plug-in (jplugin2.jar) to the build path of the Java project.

    The plug-in is a JAR file that is provided with the IBM® Integration Toolkit. The jplugin2.jar is also available in the classes directory of the server installation.

    1. In the Java perspective, right-click the Java project, and select Properties.
    2. Select Java Build Path.
    3. Select the Libraries tab.
    4. Click Add Variable.
    5. Select the variable JCN_HOME and click Extend.
    6. Select jplugin2.jar, and click OK.
  2. Import the MbElement class into your Java source.

    You must add the following code:

    import com.ibm.broker.plugin.MbElement;
    

Mapping a single non-repeating element

When you map a single non-repeating element input to a single non-repeating element output, you can use a Java method with the following signature:

public static MbElement mbElMove(MbElement inEl)

For example, the following code shows a Java method that copies a sub tree:

public static MbElement mbElMove(MbElement inEl)
      {
		MbElement outEl = null;
		try {
			outEl = inEl.copy();
			outEl.copyElementTree(inEl);
		} catch (MbException e) {
			throw (new RuntimeException(e));
		}
		return outEl;
	}

Mapping a single repeating element

When you map a single repeating element input to an output repeating element, you can use a Java method with the following signature:

public static List<MbElement>; customCompleTypeMove(List<MbElement>; inEls)

For example:

public static List<MbElement> customCompleTypeMove(List<MbElement> inEls)
      {
		List<MbElement> outEls = new ArrayList<MbElement>();
		try {
			Iterator<MbElement> i = inEls.iterator();
			while (i.hasNext()) {
				MbElement inEl = i.next();
				MbElement outEl = inEl.copy();
				// Do some processing of outEl
				outEls.add(outEl);
			}
		} catch (MbException e) {
			throw (new RuntimeException(e));
		}
		return outEls;
	}

Mapping an element by using a Custom Java transform

In the Graphical Data Mapping editor, you can use a method in a Java class to set the value of an output element. You use the Custom Java transform to invoke a Java method, optionally passing one or more values to its parameters.

When  you use a Custom Java transform, you must complete the following steps:

  1. Create a message map.
  2. Create a Java project
  3. Create Java object classes.

    The Java class that you provide to the map must have static methods that return the appropriate type for the value of the output element, and takes parameters of the appropriate type for the wired inputs.

    You can use the MbElement class in a Java method to pass a complex type, a wildcard xsd:any, or a wildcard xsd:anySimpleType.

    For example, the following Java method might be used in a Custom Java transform that has three input elements, of types a xs:string, xs:decimal, and xs:boolean and the output element is a xs:decimal:

    	public static BigDecimal calSomething(String memType, BigDecimal stdCost, boolean flag) {
    		BigDecimal actualCost = stdCost;
    		if (flag & memType.startsWith("gold")) {
    			BigDecimal discRate = new BigDecimal(0.9);
    			actualCost = actualCost.multiply(discRate);
    		}			
    		return actualCost;
    	}
    Note: If the input element being used to provide a value for a Java method is not of the correct type, you can use a type cast function, for example xs:int( $var ), to set the required type. For more information, see Cast type (xs:type).
  4. Ensure that the Java project the class is in is referenced by the project that contains the map.

    Before you create a reference to a Java project, ensure that the Java class is available in a Java project in your workspace.

    1. In the Application development page, right-click the project where the map is defined.
    2. Select Managed included projects.
    3. Select the Java project, and then click OK.

    Note: Notice that if the Java project that contains the Java class does not build in Eclipse, then the Java class is not visible anywhere in the map. You must resolve all the Java errors, which you can see in the Problems tab, before you can configure the Java imports tab in the Properties page of the map.

  5. Add a Custom Java transform to the map.
  6. Configure the method that defines the transformation logic that is applied by the Custom Java transform. In the General tab of the Properties page of the transform, complete the following steps:

    You can only configure one call to a Java method in a Custom Java transform. You can define more operations (java method or XPath expression) on the parameters that are required by the method.

    You can configure the Java class, and a Java method in the General tab of the Properties page of the transform. The method that you specify defines the transformation logic that is applied by the Custom Java transform.

    When you define a Java method and a Java class in the General tab of the Properties page of a Custom Java transform, an import is automatically added in the map to refer to the package qualified Java class. A prefix based on the class name is added. All the public static methods in this Java class are then available in content-assist when building expressions in other transforms.

    Note: The Java class that contains the method must be available in a Java project in your workspace. The Java class must be visible to the project that contains the map.

    Alternatively, you can use Java code for which you have first manually imported the Java class into the map. To manually import a Java class in a map, you configure the Java imports tab in the Properties page of the map.

    1. Configure the Java class. Click Browse and complete the following steps:
      Note: If the Java project that contains the Java class does not build in Eclipse, then the Java class is not visible anywhere in the map. You must resolve all the Java errors before you can configure the class and method in the General tab of the Properties page. You can see the errors in the Problems tab.
      1. In the Select Type window, enter the name of the Java package in the Select entries field. The package must contain the Java class.
        Note: You must start typing the name of your Java package before you can see any classes to choose from in the Select entries field.
      2. Select a Java class and click OK.
    2. Configure one Java method. You access the methods that are available through the drop-down.

      If the method has parameters, they are added automatically in the Parameters section of the General tab.

Defining a conditional expression

In a message map, you can use a Java method to set the conditional expression that determines whether a transform is applied in a message map.

To define the conditional expression, you can define an XPath expression or a call to a static method on an imported Java class. You can also create a complex expression that includes XPath, Java, and any extension functions such as mb:getUserDefinedProperty("propertyname").

Note: If you define a conditional expression for a transform, and then realize that the condition is identical for other transforms in the map, change the transform to an If transform. The conditional expression remains unchanged, and the transform is moved within the nested level of the If transform. Then, place all of the transforms that depend on the same condition in the If nested mapping.

Complete the following steps to set a conditional expression in a transform:

  1. Create a message map.
  2. Create a Java project
  3. Create Java object classes.

    The Java class that you provide to the map must have static methods that return Boolean values.

    For example, the following Java method might be used to define a conditional expression on a transform:

    public static boolean lessThanHund(BigDecimal val) {
    		if ( val.intValueExact() < 100 )
    			return true;
    		return false;
    	}	
    	
  4. Ensure that the Java project the class is in is referenced by the project that contains the map.
  5. Make the Java class visible anywhere in the map.

    Unless you have already used a method from the Java class in a Custom Java transform elsewhere in the map, you must manually create an import for the class. To manually import the Java class, you must configure the Java imports tab in the Properties page of the map:

    1. Select Add.
    2. Click Browse.
    3. In the Select entries field, enter the name of the Java package that contains the Java class.
      Note: You must start typing the name of your Java package before you can see any classes to choose from in the Select entries field.
    4. Select a Java class.
    5. Click OK.
    6. Enter a unique value in the Prefix field.
    7. For non-repeating elements, select the Condition property in the Properties tab, and enter a Java method.
      Note: Always use content assist to select the variable name of the input elements that you use to define the expressions. If you do not use content assist, you might be using an incorrect element name and your map fails at run time.

      You can identify the Java method in content assist by using the prefix. For example, in the following figure the prefix is Conditionals and the method is lessThanHund():

      Conditionals:lessThanHund( $element11)
      Note: If the input element being used to provide a value for a Java method is not of the correct type, you can use a type cast function, for example xs:int( $var ), to set the required type. For more information, see Cast type (xs:type).
    8. For repeating elements, select the Filter Inputs property in the Properties tab, and enter a Java method that is applied to each instance of the repeating element.

If the Java method returns true, the transform is applied to the input element.

Altering the value of an input argument to an XPath function

You alter the value in the Properties page of the XPath function.

You can use content assist in the Value column that is available in the General tab to help you assign the elements of the source schema.

2 comments on"How to use Java in a Message Map (Graphical data map) in IBM Integration Bus?"

  1. martin paiz December 18, 2017

    is it possible consume a web service that return an array of strings and create a hashmap with those values? Could you show me an example? Thanks

    Reply (Edit)
    • martin_b December 19, 2017

      Hi Martin

      Please take a look at the IIB Knowledge Center topic “Processing complex or repeating elements in a Custom Java transform”
      https://www.ibm.com/support/knowledgecenter/en/SSMKHH_10.0.0/com.ibm.gdm.doc/br28868_.htm

      This shows how you can map a single repeating element using by receiving elements of the input message via an “List“. You could use this to populate the values into the Hashmap.

      HTH
      Martin

      Reply (Edit)

#IntegrationBus(IIB)
#GDM
#graphicaldatamapping
#Java